From f499c957fc5f7cba7545968f69343640db27dfcd Mon Sep 17 00:00:00 2001 From: Ekaterina Mekhnetsova Date: Tue, 1 Dec 2020 22:40:43 +0300 Subject: [PATCH 1/4] Added doxygen comments from spec --- cpp/oneapi/dal/algo/kmeans/common.hpp | 45 +++- cpp/oneapi/dal/algo/kmeans/infer_types.hpp | 19 ++ cpp/oneapi/dal/algo/kmeans/train_types.hpp | 23 ++ cpp/oneapi/dal/algo/kmeans_init/common.hpp | 30 ++- .../dal/algo/kmeans_init/compute_types.hpp | 12 + cpp/oneapi/dal/algo/knn/common.hpp | 38 ++- cpp/oneapi/dal/algo/knn/infer_types.hpp | 13 + cpp/oneapi/dal/algo/knn/train_types.hpp | 13 + cpp/oneapi/dal/algo/pca/common.hpp | 45 +++- cpp/oneapi/dal/algo/pca/infer_types.hpp | 14 ++ cpp/oneapi/dal/algo/pca/train_types.hpp | 26 ++ cpp/oneapi/dal/array.hpp | 231 ++++++++++++++++++ cpp/oneapi/dal/table/column_accessor.hpp | 36 +++ cpp/oneapi/dal/table/common.hpp | 44 ++++ cpp/oneapi/dal/table/homogen.hpp | 75 ++++++ cpp/oneapi/dal/table/row_accessor.hpp | 32 +++ 16 files changed, 675 insertions(+), 21 deletions(-) diff --git a/cpp/oneapi/dal/algo/kmeans/common.hpp b/cpp/oneapi/dal/algo/kmeans/common.hpp index 55b6627b47e..cc2d92cbd33 100644 --- a/cpp/oneapi/dal/algo/kmeans/common.hpp +++ b/cpp/oneapi/dal/algo/kmeans/common.hpp @@ -23,8 +23,12 @@ namespace oneapi::dal::kmeans { namespace task { namespace v1 { -struct clustering {}; -using by_default = clustering; + /// Tag-type that parameterizes entities used for solving + /// :capterm:`clustering problem `. + struct clustering {}; + + /// Alias tag-type for the clustering task. + using by_default = clustering; } // namespace v1 using v1::clustering; @@ -34,8 +38,13 @@ using v1::by_default; namespace method { namespace v1 { -struct lloyd_dense {}; -using by_default = lloyd_dense; + /// Tag-type that denotes `Lloyd's `_ computational + /// method. + struct lloyd_dense {}; + + /// Alias tag-type for `Lloyd's `_ computational + /// method. + using by_default = lloyd_dense; } // namespace v1 using v1::lloyd_dense; @@ -74,8 +83,19 @@ class descriptor_base : public base { descriptor_base(); + /// The number of clusters $k$ + /// @invariant :expr:`cluster_count > 0` + /// @remark default = 2 std::int64_t get_cluster_count() const; + + /// The maximum number of iterations $T$ + /// @invariant :expr:`max_iteration_count >= 0` + /// @remark default = 100 std::int64_t get_max_iteration_count() const; + + /// The threshold $\\varepsilon$ for the stop condition + /// @invariant :expr:`accuracy_threshold >= 0.0` + /// @remark default = 0.0 double get_accuracy_threshold() const; protected: @@ -102,6 +122,13 @@ using v1::is_valid_task_v; namespace v1 { +/// @tparam Float The floating-point type that the algorithm uses for +/// intermediate computations. Can be :expr:`float` or +/// :expr:`double`. +/// @tparam Method Tag-type that specifies an implementation of algorithm. Can +/// be :expr:`method::lloyd`. +/// @tparam Task Tag-type that specifies the type of the problem to solve. Can +/// be :expr:`task::clustering`. template ::float_t, typename Method = detail::descriptor_base<>::method_t, typename Task = detail::descriptor_base<>::task_t> @@ -117,6 +144,7 @@ class descriptor : public detail::descriptor_base { using method_t = Method; using task_t = Task; + /// Creates a new instance of the class with the given :literal:`cluster_count` explicit descriptor(std::int64_t cluster_count = 2) { set_cluster_count(cluster_count); } @@ -137,6 +165,8 @@ class descriptor : public detail::descriptor_base { } }; +/// @tparam Task Tag-type that specifies type of the problem to solve. Can +/// be :expr:`task::clustering`. template class model : public base { static_assert(detail::is_valid_task_v); @@ -145,8 +175,12 @@ class model : public base { public: using task_t = Task; + /// Creates a new instance of the class with the default property values. model(); + /// A $k \\times p$ table with the cluster centroids. Each row of the + /// table stores one centroid. + /// @remark default = table{} const table& get_centroids() const; auto& set_centroids(const table& value) { @@ -154,6 +188,9 @@ class model : public base { return *this; } + /// Number of clusters $k$ in the trained model. + /// @invariant :expr:`cluster_count == centroids.row_count` + /// @remark default = 0 std::int64_t get_cluster_count() const; protected: diff --git a/cpp/oneapi/dal/algo/kmeans/infer_types.hpp b/cpp/oneapi/dal/algo/kmeans/infer_types.hpp index 0553dcb4507..822947d6af3 100644 --- a/cpp/oneapi/dal/algo/kmeans/infer_types.hpp +++ b/cpp/oneapi/dal/algo/kmeans/infer_types.hpp @@ -36,6 +36,8 @@ using v1::infer_result_impl; namespace v1 { +/// @tparam Task Tag-type that specifies type of the problem to solve. Can +/// be :expr:`task::clustering`. template class infer_input : public base { static_assert(detail::is_valid_task_v); @@ -43,8 +45,13 @@ class infer_input : public base { public: using task_t = Task; + /// Creates a new instance of the class with the given :literal:`model` and + /// :literal:`data` infer_input(const model& trained_model, const table& data); + /// An $n \\times p$ table with the data to be assigned to the clusters, + /// where each row stores one feature vector. + /// @remark default = model{} const model& get_model() const; auto& set_model(const model& value) { @@ -52,6 +59,8 @@ class infer_input : public base { return *this; } + /// The trained K-Means model + /// @remark default = table{} const table& get_data() const; auto& set_data(const table& value) { @@ -67,6 +76,8 @@ class infer_input : public base { dal::detail::pimpl> impl_; }; +/// @tparam Task Tag-type that specifies type of the problem to solve. Can +/// be :expr:`task::clustering`. template class infer_result { static_assert(detail::is_valid_task_v); @@ -74,14 +85,22 @@ class infer_result { public: using task_t = Task; + /// Creates a new instance of the class with the default property values. infer_result(); + /// An $n \\times 1$ table with assignments labels to feature + /// vectors in the input data. + /// @remark default = table{} const table& get_labels() const; auto& set_labels(const table& value) { set_labels_impl(value); return *this; } + /// The value of the objective function $\\Phi_X(C)$, where $C$ is + /// defined by the corresponding :expr:`infer_input::model::centroids`. + /// @invariant :expr:`objective_function_value >= 0.0` + /// @remark default = 0.0 double get_objective_function_value() const; auto& set_objective_function_value(double value) { diff --git a/cpp/oneapi/dal/algo/kmeans/train_types.hpp b/cpp/oneapi/dal/algo/kmeans/train_types.hpp index 97f78814a03..3cd8f767837 100644 --- a/cpp/oneapi/dal/algo/kmeans/train_types.hpp +++ b/cpp/oneapi/dal/algo/kmeans/train_types.hpp @@ -36,6 +36,8 @@ using v1::train_result_impl; namespace v1 { +/// @tparam Task Tag-type that specifies type of the problem to solve. Can +/// be :expr:`task::clustering`. template class train_input : public base { static_assert(detail::is_valid_task_v); @@ -44,8 +46,13 @@ class train_input : public base { using task_t = Task; train_input(const table& data); + + /// Creates a new instance of the class with the given :literal:`data` and + /// :literal:`initial_centroids` train_input(const table& data, const table& initial_centroids); + /// An $n \\times p$ table with the data to be clustered, where each row + /// stores one feature vector. const table& get_data() const; auto& set_data(const table& data) { @@ -53,6 +60,8 @@ class train_input : public base { return *this; } + /// A $k \\times p$ table with the initial centroids, where each row + /// stores one centroid. const table& get_initial_centroids() const; auto& set_initial_centroids(const table& data) { @@ -68,6 +77,8 @@ class train_input : public base { dal::detail::pimpl> impl_; }; +/// @tparam Task Tag-type that specifies type of the problem to solve. Can +/// be :expr:`task::clustering`. template class train_result { static_assert(detail::is_valid_task_v); @@ -75,8 +86,11 @@ class train_result { public: using task_t = Task; + /// Creates a new instance of the class with the default property values. train_result(); + /// The trained K-means model + /// @remark default = model{} const model& get_model() const; auto& set_model(const model& value) { @@ -84,6 +98,9 @@ class train_result { return *this; } + /// An $n \\times 1$ table with the labels $y_i$ assigned to the + /// samples $x_i$ in the input data, $1 \\leq 1 \\leq n$. + /// @remark default = table{} const table& get_labels() const; auto& set_labels(const table& value) { @@ -91,6 +108,9 @@ class train_result { return *this; } + /// The number of iterations performed by the algorithm. + /// @remark default = 0 + /// @invariant :expr:`iteration_count >= 0` int64_t get_iteration_count() const; auto& set_iteration_count(std::int64_t value) { @@ -98,6 +118,9 @@ class train_result { return *this; } + /// The value of the objective function $\\Phi_X(C)$, where $C$ is + /// :expr:`model.centroids` (see :expr:`kmeans::model::centroids`). + /// @invariant :expr:`objective_function_value >= 0.0` double get_objective_function_value() const; auto& set_objective_function_value(double value) { diff --git a/cpp/oneapi/dal/algo/kmeans_init/common.hpp b/cpp/oneapi/dal/algo/kmeans_init/common.hpp index e43e7d6f684..e1a48270dde 100644 --- a/cpp/oneapi/dal/algo/kmeans_init/common.hpp +++ b/cpp/oneapi/dal/algo/kmeans_init/common.hpp @@ -23,8 +23,11 @@ namespace oneapi::dal::kmeans_init { namespace task { namespace v1 { -struct init {}; -using by_default = init; + /// Tag-type that parameterizes entities used for obtaining the initial K-Means centroids. + struct init {}; + + /// Alias tag-type for the initialization task. + using by_default = init; } // namespace v1 using v1::init; @@ -34,11 +37,13 @@ using v1::by_default; namespace method { namespace v1 { -struct dense {}; -struct random_dense {}; -struct plus_plus_dense {}; -struct parallel_plus_dense {}; -using by_default = dense; + /// Tag-type that denotes `dense `_ + /// computational method. + struct dense {}; + struct random_dense {}; + struct plus_plus_dense {}; + struct parallel_plus_dense {}; + using by_default = dense; } // namespace v1 using v1::dense; @@ -81,6 +86,9 @@ class descriptor_base : public base { descriptor_base(); + /// The number of clusters $k$ + /// @invariant :expr:`cluster_count > 0` + /// @remark default = 2 std::int64_t get_cluster_count() const; protected: @@ -104,6 +112,13 @@ using v1::is_valid_task_v; namespace v1 { +/// @tparam Float The floating-point type that the algorithm uses for +/// intermediate computations. Can be :expr:`float` or +/// :expr:`double`. +/// @tparam Method Tag-type that specifies an implementation +/// of K-Means Initialization algorithm. +/// @tparam Task Tag-type that specifies the type of the problem to solve. Can +/// be :expr:`task::init`. template ::float_t, typename Method = detail::descriptor_base<>::method_t, typename Task = detail::descriptor_base<>::task_t> @@ -119,6 +134,7 @@ class descriptor : public detail::descriptor_base { using method_t = Method; using task_t = Task; + /// Creates a new instance of the class with the given :literal:`cluster_count` explicit descriptor(std::int64_t cluster_count = 2) { set_cluster_count(cluster_count); } diff --git a/cpp/oneapi/dal/algo/kmeans_init/compute_types.hpp b/cpp/oneapi/dal/algo/kmeans_init/compute_types.hpp index 6d0833feeb6..5cd02c2df83 100644 --- a/cpp/oneapi/dal/algo/kmeans_init/compute_types.hpp +++ b/cpp/oneapi/dal/algo/kmeans_init/compute_types.hpp @@ -36,6 +36,8 @@ using v1::compute_result_impl; namespace v1 { +/// @tparam Task Tag-type that specifies type of the problem to solve. Can +/// be :expr:`task::init`. template class compute_input : public base { static_assert(detail::is_valid_task_v); @@ -43,8 +45,12 @@ class compute_input : public base { public: using task_t = Task; + /// Creates a new instance of the class with the given :literal:`data`. compute_input(const table& data); + /// An $n \\times p$ table with the data to be clustered, where each row + /// stores one feature vector. + /// @remark default = table{} const table& get_data() const; auto& set_data(const table& data) { @@ -58,6 +64,8 @@ class compute_input : public base { dal::detail::pimpl> impl_; }; +/// @tparam Task Tag-type that specifies type of the problem to solve. Can +/// be :expr:`task::clustering`. template class compute_result { static_assert(detail::is_valid_task_v); @@ -65,8 +73,12 @@ class compute_result { public: using task_t = Task; + /// Creates a new instance of the class with the default property values. compute_result(); + /// A $k \\times p$ table with the initial centroids. Each row of the + /// table stores one centroid. + /// @remark default = table{} const table& get_centroids() const; auto& set_centroids(const table& value) { diff --git a/cpp/oneapi/dal/algo/knn/common.hpp b/cpp/oneapi/dal/algo/knn/common.hpp index 9a75d50427b..a67f0f79624 100644 --- a/cpp/oneapi/dal/algo/knn/common.hpp +++ b/cpp/oneapi/dal/algo/knn/common.hpp @@ -23,8 +23,12 @@ namespace oneapi::dal::knn { namespace task { namespace v1 { -struct classification {}; -using by_default = classification; + /// Tag-type that parameterizes entities used for solving + /// :capterm:`classification problem `. + struct classification {}; + + /// Alias tag-type for classification task. + using by_default = classification; } // namespace v1 using v1::classification; @@ -34,9 +38,16 @@ using v1::by_default; namespace method { namespace v1 { -struct kd_tree {}; -struct brute_force {}; -using by_default = brute_force; + /// Tag-type that denotes `k-d tree `_ computational method. + struct kd_tree {}; + + /// Tag-type that denotes `brute-force `_ computational + /// method. + struct brute_force {}; + + /// Alias tag-type for `brute-force `_ computational + /// method. + using by_default = brute_force; } // namespace v1 using v1::kd_tree; @@ -76,7 +87,12 @@ class descriptor_base : public base { descriptor_base(); + /// The number of classes $c$ + /// @invariant :expr:`class_count > 1` std::int64_t get_class_count() const; + + /// The number of neighbors $k$ + /// @invariant :expr:`neighbor_count > 0` std::int64_t get_neighbor_count() const; protected: @@ -102,6 +118,13 @@ using v1::is_valid_task_v; namespace v1 { +/// @tparam Float The floating-point type that the algorithm uses for +/// intermediate computations. Can be :expr:`float` or +/// :expr:`double`. +/// @tparam Method Tag-type that specifies an implementation of algorithm. Can +/// be :expr:`method::bruteforce` or :expr:`method::kd_tree`. +/// @tparam Task Tag-type that specifies type of the problem to solve. Can +/// be :expr:`task::classification`. template ::float_t, typename Method = detail::descriptor_base<>::method_t, typename Task = detail::descriptor_base<>::task_t> @@ -117,6 +140,8 @@ class descriptor : public detail::descriptor_base { using method_t = Method; using task_t = Task; + /// Creates a new instance of the class with the given :literal:`class_count` + /// and :literal:`neighbor_count` property values explicit descriptor(std::int64_t class_count, std::int64_t neighbor_count) { set_class_count(class_count); set_neighbor_count(neighbor_count); @@ -133,12 +158,15 @@ class descriptor : public detail::descriptor_base { } }; +/// @tparam Task Tag-type that specifies type of the problem to solve. Can +/// be :expr:`task::classification`. template class model : public base { static_assert(detail::is_valid_task_v); friend dal::detail::pimpl_accessor; public: + /// Creates a new instance of the class with the default property values. model(); private: diff --git a/cpp/oneapi/dal/algo/knn/infer_types.hpp b/cpp/oneapi/dal/algo/knn/infer_types.hpp index 7eb329be8da..68c0af09ebc 100644 --- a/cpp/oneapi/dal/algo/knn/infer_types.hpp +++ b/cpp/oneapi/dal/algo/knn/infer_types.hpp @@ -36,6 +36,8 @@ using v1::infer_result_impl; namespace v1 { +/// @tparam Task Tag-type that specifies type of the problem to solve. Can +/// be :expr:`task::classification`. template class infer_input : public base { static_assert(detail::is_valid_task_v); @@ -43,8 +45,12 @@ class infer_input : public base { public: using task_t = Task; + /// Creates a new instance of the class with the given :literal:`model` + /// and :literal:`data` property values infer_input(const table& data, const model& model); + /// The dataset for inference $X'$ + /// @remark default = table{} const table& get_data() const; auto& set_data(const table& data) { @@ -52,6 +58,8 @@ class infer_input : public base { return *this; } + /// The trained $k$-NN model + /// @remark default = model{} const model& get_model() const; auto& set_model(const model& m) { @@ -67,6 +75,8 @@ class infer_input : public base { dal::detail::pimpl> impl_; }; +/// @tparam Task Tag-type that specifies type of the problem to solve. Can +/// be :expr:`task::classification`. template class infer_result { static_assert(detail::is_valid_task_v); @@ -74,8 +84,11 @@ class infer_result { public: using task_t = Task; + /// Creates a new instance of the class with the default property values. infer_result(); + /// The predicted labels + /// @remark default = table{} const table& get_labels() const; auto& set_labels(const table& value) { diff --git a/cpp/oneapi/dal/algo/knn/train_types.hpp b/cpp/oneapi/dal/algo/knn/train_types.hpp index 4818ed431c7..e5f5f911153 100644 --- a/cpp/oneapi/dal/algo/knn/train_types.hpp +++ b/cpp/oneapi/dal/algo/knn/train_types.hpp @@ -36,6 +36,8 @@ using v1::train_result_impl; namespace v1 { +/// @tparam Task Tag-type that specifies type of the problem to solve. Can +/// be :expr:`task::classification`. template class train_input : public base { static_assert(detail::is_valid_task_v); @@ -43,8 +45,12 @@ class train_input : public base { public: using task_t = Task; + /// Creates a new instance of the class with the given :literal:`data` + /// and :literal:`labels` property values train_input(const table& data, const table& labels); + /// The training set $X$ + /// @remark default = table{} const table& get_data() const; auto& set_data(const table& data) { @@ -52,6 +58,8 @@ class train_input : public base { return *this; } + /// Vector of labels $y$ for the training set $X$ + /// @remark default = table{} const table& get_labels() const; auto& set_labels(const table& labels) { @@ -67,6 +75,8 @@ class train_input : public base { dal::detail::pimpl> impl_; }; +/// @tparam Task Tag-type that specifies type of the problem to solve. Can +/// be :expr:`task::classification`. template class train_result { static_assert(detail::is_valid_task_v); @@ -74,8 +84,11 @@ class train_result { public: using task_t = Task; + /// Creates a new instance of the class with the default property values. train_result(); + /// The trained $k$-NN model + /// @remark default = model{} const model& get_model() const; auto& set_model(const model& value) { diff --git a/cpp/oneapi/dal/algo/pca/common.hpp b/cpp/oneapi/dal/algo/pca/common.hpp index c31507796c2..84e28a30c9c 100644 --- a/cpp/oneapi/dal/algo/pca/common.hpp +++ b/cpp/oneapi/dal/algo/pca/common.hpp @@ -23,8 +23,12 @@ namespace oneapi::dal::pca { namespace task { namespace v1 { -struct dim_reduction {}; -using by_default = dim_reduction; + /// Tag-type that parameterizes entities used for solving + /// :capterm:`dimensionality reduction problem `. + struct dim_reduction {}; + + /// Alias tag-type for dimensionality reduction task. + using by_default = dim_reduction; } // namespace v1 using v1::dim_reduction; @@ -34,9 +38,16 @@ using v1::by_default; namespace method { namespace v1 { -struct cov {}; -struct svd {}; -using by_default = cov; + /// Tag-type that denotes `Covariance `_ computational + /// method. + struct cov {}; + + /// Tag-type that denotes `SVD `_ computational method. + struct svd {}; + + /// Alias tag-type for `Covariance `_ computational + /// method. + using by_default = cov; } // namespace v1 using v1::cov; @@ -76,7 +87,15 @@ class descriptor_base : public base { descriptor_base(); + /// The number of principal components $r$. If it is zero, the algorithm + /// computes the eigenvectors for all features, $r = p$. + /// @remark default = 0 + /// @invariant :expr:`component_count >= 0` std::int64_t get_component_count() const; + + /// Specifies whether the algorithm applies the `Sign-flip technique`_. + /// If it is `true`, the directions of the eigenvectors must be deterministic. + /// @remark default = true bool get_deterministic() const; protected: @@ -102,6 +121,13 @@ using v1::is_valid_task_v; namespace v1 { +/// @tparam Float The floating-point type that the algorithm uses for +/// intermediate computations. Can be :expr:`float` or +/// :expr:`double`. +/// @tparam Method Tag-type that specifies an implementation of algorithm. Can +/// be :expr:`method::cov` or :expr:`method::svd`. +/// @tparam Task Tag-type that specifies type of the problem to solve. Can +/// be :expr:`task::dim_reduction`. template ::float_t, typename Method = detail::descriptor_base<>::method_t, typename Task = detail::descriptor_base<>::task_t> @@ -117,6 +143,9 @@ class descriptor : public detail::descriptor_base { using method_t = Method; using task_t = Task; + + /// Creates a new instance of the class with the given :literal:`component_count` + /// property value explicit descriptor(std::int64_t component_count = 0) { set_component_count(component_count); } @@ -132,6 +161,8 @@ class descriptor : public detail::descriptor_base { } }; +/// @tparam Task Tag-type that specifies type of the problem to solve. Can +/// be :expr:`task::dim_reduction`. template class model : public base { static_assert(detail::is_valid_task_v); @@ -140,8 +171,12 @@ class model : public base { public: using task_t = Task; + /// Creates a new instance of the class with the default property values. model(); + /// An $r \\times p$ table with the eigenvectors. Each row contains one + /// eigenvector. + /// @remark default = table{} const table& get_eigenvectors() const; auto& set_eigenvectors(const table& value) { diff --git a/cpp/oneapi/dal/algo/pca/infer_types.hpp b/cpp/oneapi/dal/algo/pca/infer_types.hpp index 0d9b6a7fa3a..2005248a0af 100644 --- a/cpp/oneapi/dal/algo/pca/infer_types.hpp +++ b/cpp/oneapi/dal/algo/pca/infer_types.hpp @@ -36,6 +36,8 @@ using v1::infer_result_impl; namespace v1 { +/// @tparam Task Tag-type that specifies type of the problem to solve. Can +/// be :expr:`task::dim_reduction`. template class infer_input : public base { static_assert(detail::is_valid_task_v); @@ -43,8 +45,12 @@ class infer_input : public base { public: using task_t = Task; + /// Creates a new instance of the class with the given :literal:`model` + /// and :literal:`data` property values infer_input(const model& trained_model, const table& data); + /// The trained PCA model + /// @remark default = model{} const model& get_model() const; auto& set_model(const model& value) { @@ -52,6 +58,8 @@ class infer_input : public base { return *this; } + /// The dataset for inference $X'$ + /// @remark default = table{} const table& get_data() const; auto& set_data(const table& value) { @@ -67,6 +75,8 @@ class infer_input : public base { dal::detail::pimpl> impl_; }; +/// @tparam Task Tag-type that specifies type of the problem to solve. Can +/// be :expr:`task::dim_reduction`. template class infer_result { static_assert(detail::is_valid_task_v); @@ -74,8 +84,12 @@ class infer_result { public: using task_t = Task; + /// Creates a new instance of the class with the default property values. infer_result(); + /// An $n \\times r$ table that contains data projected to the $r$ + /// principal components. + /// @remark default = table{} const table& get_transformed_data() const; auto& set_transformed_data(const table& value) { diff --git a/cpp/oneapi/dal/algo/pca/train_types.hpp b/cpp/oneapi/dal/algo/pca/train_types.hpp index 080fafafbbb..42f2073dbb4 100644 --- a/cpp/oneapi/dal/algo/pca/train_types.hpp +++ b/cpp/oneapi/dal/algo/pca/train_types.hpp @@ -36,6 +36,8 @@ using v1::train_result_impl; namespace v1 { +/// @tparam Task Tag-type that specifies type of the problem to solve. Can +/// be :expr:`task::dim_reduction`. template class train_input : public base { static_assert(detail::is_valid_task_v); @@ -43,8 +45,13 @@ class train_input : public base { public: using task_t = Task; + /// Creates a new instance of the class with the given :literal:`data` + /// property value train_input(const table& data); + /// An $n \\times p$ table with the training data, where each row stores one + /// feature vector. + /// @remark default = table{} const table& get_data() const; auto& set_data(const table& data) { @@ -59,6 +66,8 @@ class train_input : public base { dal::detail::pimpl> impl_; }; +/// @tparam Task Tag-type that specifies type of the problem to solve. Can +/// be :expr:`task::dim_reduction`. template class train_result { static_assert(detail::is_valid_task_v); @@ -66,10 +75,18 @@ class train_result { public: using task_t = Task; + /// Creates a new instance of the class with the default property values. train_result(); + + /// An $r \\times p$ table with the eigenvectors. Each row contains one + /// eigenvector. + /// @remark default = table{} + /// @invariant :expr:`eigenvectors == model.eigenvectors` const table& get_eigenvectors() const; + /// The trained PCA model + /// @remark default = model{} const model& get_model() const; auto& set_model(const model& value) { @@ -77,6 +94,9 @@ class train_result { return *this; } + /// A $1 \\times r$ table that contains the eigenvalues for for the first + /// $r$ features. + /// @remark default = table{} const table& get_eigenvalues() const; auto& set_eigenvalues(const table& value) { @@ -84,6 +104,9 @@ class train_result { return *this; } + /// A $1 \\times r$ table that contains the variances for the first $r$ + /// features. + /// @remark default = table{} const table& get_variances() const; auto& set_variances(const table& value) { @@ -91,6 +114,9 @@ class train_result { return *this; } + /// A $1 \\times r$ table that contains the mean values for the first $r$ + /// features. + /// @remark default = table{} const table& get_means() const; auto& set_means(const table& value) { diff --git a/cpp/oneapi/dal/array.hpp b/cpp/oneapi/dal/array.hpp index a8707ab946d..d72c4f750b8 100644 --- a/cpp/oneapi/dal/array.hpp +++ b/cpp/oneapi/dal/array.hpp @@ -24,6 +24,10 @@ namespace oneapi::dal { namespace v1 { +/// @tparam T The type of the memory block elements within the array. +/// $T$ can represent any type. +/// +/// @pre $T$ cannot be const-qualified. template class array { static_assert(!std::is_const_v, "array class cannot have const-qualified type of data"); @@ -37,6 +41,12 @@ class array { using data_t = T; public: + /// Allocates a new memory block for mutable data, does not initialize it, + /// creates a new array instance by passing a pointer to the memory block. + /// The array owns the memory block (for details, see :txtref:`data_ownership_requirements`). + /// + /// @param count The number of elements of type $Data$ to allocate memory for. + /// @pre :expr:`count > 0` static array empty(std::int64_t count) { return array{ impl_t::empty(detail::default_host_policy{}, count, detail::host_allocator()) @@ -44,6 +54,15 @@ class array { } #ifdef ONEDAL_DATA_PARALLEL + + /// Allocates a new memory block for mutable data, does not initialize it, + /// creates a new array instance by passing a pointer to the memory block. + /// The array owns the memory block (for details, see :txtref:`data_ownership_requirements`). + /// + /// @param queue The SYCL* queue object. + /// @param count The number of elements of type $T$ to allocate memory for. + /// @param alloc The kind of USM to be allocated. + /// @pre :expr:`count > 0` static array empty(const sycl::queue& queue, std::int64_t count, const sycl::usm::alloc& alloc = sycl::usm::alloc::shared) { @@ -53,6 +72,16 @@ class array { } #endif + /// Allocates a new memory block for mutable data, fills it with a scalar value, + /// creates a new array instance by passing a pointer to the memory block. + /// The array owns the memory block (for details, see :txtref:`data_ownership_requirements`). + /// + /// @tparam Element The type from which array elements of type $T$ can be constructed. + /// + /// @param count The number of elements of type $T$ to allocate memory for. + /// @param element The value that is used to fill a memory block. + /// @pre :expr:`count > 0` + /// @pre Elements of type ``T`` are constructible from the ``Element`` type. template static array full(std::int64_t count, K&& element) { return array{ impl_t::full(detail::default_host_policy{}, @@ -62,6 +91,18 @@ class array { } #ifdef ONEDAL_DATA_PARALLEL + /// Allocates a new memory block for mutable data, fills it with a scalar value, + /// creates a new array instance by passing a pointer to the memory block. + /// The array owns the memory block (for details, see :txtref:`data_ownership_requirements`). + /// + /// @tparam Element The type from which array elements of type $Data$ can be constructed. + /// + /// @param queue The SYCL* queue object. + /// @param count The number of elements of type $Data$ to allocate memory for. + /// @param element The value that is used to fill a memory block. + /// @param alloc The kind of USM to be allocated. + /// @pre :expr:`count > 0` + /// @pre Elements of type ``Data`` are constructible from the ``Element`` type. template static array full(sycl::queue& queue, std::int64_t count, @@ -74,6 +115,12 @@ class array { } #endif + /// Allocates a new memory block on mutable data, fills it with zeros, + /// creates a new array instance by passing a pointer to the memory block. + /// The array owns the memory block (for details, see :txtref:`data_ownership_requirements`). + /// + /// @param count The number of elements of type $Data$ to allocate memory for. + /// @pre :expr:`count > 0` static array zeros(std::int64_t count) { // TODO: can be optimized in future return array{ @@ -82,6 +129,15 @@ class array { } #ifdef ONEDAL_DATA_PARALLEL + + /// Allocates a new memory block on mutable data, fills it with zeros, + /// creates a new array instance by passing a pointer to the memory block. + /// The array owns the memory block (for details, see :txtref:`data_ownership_requirements`). + /// + /// @param queue The SYCL* queue object. + /// @param count The number of elements of type $T$ to allocate memory for. + /// @param alloc The kind of USM to be allocated. + /// @pre :expr:`count > 0`s static array zeros(sycl::queue& queue, std::int64_t count, const sycl::usm::alloc& alloc = sycl::usm::alloc::shared) { @@ -92,12 +148,31 @@ class array { detail::data_parallel_allocator(queue, alloc)) }; } #endif + + /// Creates a new array instance by passing the pointer to externally-allocated memory block + /// for mutable data. It is the responsibility of the calling application to free the memory block + /// as the array does not free it when the reference count is zero. + /// + /// @param data The pointer to externally-allocated memory block. + /// @param count The number of elements of type $Data$ in the memory block. + /// @pre :expr:`data != nullptr` + /// @pre :expr:`count > 0` template static array wrap(Y* data, std::int64_t count) { return array{ data, count, dal::detail::empty_delete{} }; } #ifdef ONEDAL_DATA_PARALLEL + + /// Creates a new array instance by passing the pointer to externally-allocated memory block + /// for mutable data. It is the responsibility of the calling application to free the memory block + /// as the array does not free it when the reference count is zero. + /// + /// @param data The pointer to externally-allocated memory block. + /// @param count The number of elements of type $T$ in the memory block. + /// @param dependencies Events indicating availability of the $data$ for reading or writing. + /// @pre :expr:`data != nullptr` + /// @pre :expr:`count > 0` template static array wrap(Y* data, std::int64_t count, @@ -107,25 +182,51 @@ class array { #endif public: + /// Creates a new instance of the class without memory allocation: + /// :expr:`mutable_data` and :expr:`data` pointers should be set to ``nullptr``, + /// :expr:`count` should be zero; the pointer to the ownership structure should be set to ``nullptr``. array() : impl_(new impl_t()) { const T* null_data = nullptr; update_data(null_data, 0); } + /// Creates a new array instance that shares an ownership with $other$ on its memory block. array(const array& a) : impl_(new impl_t(*a.impl_)) { update_data(impl_.get()); } + /// Moves :expr:`data`, :expr:`mutable_data` pointers, :expr:`count`, and pointer to the ownership structure + /// in $other$ to the new array instance array(array&& a) : impl_(std::move(a.impl_)) { update_data(impl_.get()); } + /// Creates a new array instance which owns a memory block of externally-allocated mutable data. + /// The ownership structure is created for a block, the input $deleter$ + /// is assigned to it. + /// + /// @tparam Deleter The type of a deleter used to free the $data$. + /// The deleter provides ``void operator()(Data*)`` member function. + /// + /// @param data The pointer to externally-allocated memory block. + /// @param count The number of elements of type $Data$ in the memory block. + /// @param deleter The object used to free $data$. template explicit array(T* data, std::int64_t count, Deleter&& deleter) : impl_(new impl_t(data, count, std::forward(deleter))) { update_data(impl_.get()); } + /// Creates a new array instance which owns a memory block of externally-allocated immutable data. + /// The ownership structure is created for a block, the input $deleter$ + /// is assigned to it. + /// + /// @tparam ConstDeleter The type of a deleter used to free the $data$. + /// The deleter implements ``void operator()(const Data*)`` member function. + /// + /// @param data The pointer to externally-allocated memory block. + /// @param count The number of elements of type $Data$ in the $data$. + /// @param deleter The object used to free $data$. template explicit array(const T* data, std::int64_t count, ConstDeleter&& deleter) : impl_(new impl_t(data, count, std::forward(deleter))) { @@ -133,6 +234,18 @@ class array { } #ifdef ONEDAL_DATA_PARALLEL + /// Creates a new array instance which owns a memory block of externally-allocated mutable data. + /// The ownership structure is created for a block, the input $deleter$ + /// is assigned to it. + /// + /// @tparam Deleter The type of a deleter used to free the $data$. + /// The deleter provides ``void operator()(T*)`` member function. + /// + /// @param queue The SYCL* queue object. + /// @param data The pointer to externally-allocated memory block. + /// @param count The number of elements of type $T$ in the memory block. + /// @param deleter The object used to free $data$. + /// @param dependencies Events that indicate when $data$ becomes ready to be read or written template explicit array(const sycl::queue& queue, T* data, @@ -144,6 +257,17 @@ class array { detail::wait_and_throw(dependencies); } + /// Creates the ownership structure for memory block of externally-allocated immutable data, + /// assigns input $deleter$ object to it, + /// sets :expr:`data` pointer to this block. + /// + /// @tparam ConstDeleter The type of a deleter used to free. + /// The deleter implements `void operator()(const T*)`` member function. + /// + /// @param data The immutable memory block pointer to be assigned inside the array + /// @param count The number of elements of type $T$ into the block + /// @param deleter The object used to free $data$. + /// @param dependencies Events indicating availability of the $data$ for reading or writing. template explicit array(const sycl::queue& queue, const T* data, @@ -156,23 +280,49 @@ class array { } #endif + /// An aliasing constructor: creates a new array instance that stores $data$ pointer, + /// assigns the pointer to the ownership structure of $ref$ to the new instance. + /// Array returns $data$ pointer as its mutable or immutable block depending + /// on the $data$ type. + /// + /// @tparam ref The type of elements in the referenced array. + /// @tparam data Either $T$ or $const T$ type. + /// + /// @param ref The array which shares ownership structure with created + /// one. + /// @param data Mutable or immutable unmanaged pointer hold by + /// created array. + /// @param count The number of elements of type $T$ in the $data$. + /// + /// @pre :expr:`std::is_same_v || std::is_same_v` template explicit array(const array& ref, K* data, std::int64_t count) : impl_(new impl_t(*ref.impl_, data, count)) { update_data(impl_.get()); } + /// Replaces the :expr:`data`, :expr:`mutable_data` pointers, :expr:`count`, and pointer + /// to the ownership structure in the array instance by the values in $other$. + /// + /// @post :expr:`data == other.data` + /// @post :expr:`mutable_data == other.mutable_data` + /// @post :expr:`count == other.count` array operator=(const array& other) { array tmp{ other }; swap(*this, tmp); return *this; } + /// Swaps the values of :expr:`data`, :expr:`mutable_data` pointers, :expr:`count`, and pointer + /// to the ownership structure in the array instance and $other$. array operator=(array&& other) { swap(*this, other); return *this; } + /// The pointer to the memory block holding mutable data. + /// @pre :expr:`has_mutable_data() == true`, othewise throws `domain_error` + /// @invariant :expr:`mutable_data != nullptr` if :expr:`has_mutable_data() && count > 0` T* get_mutable_data() const { if (!has_mutable_data()) { throw domain_error(dal::detail::error_messages::array_does_not_contain_mutable_data()); @@ -180,14 +330,27 @@ class array { return mutable_data_ptr_; } + /// The pointer to the memory block holding immutable data. + /// @invariant :expr:`data != nullptr` if :expr:`count > 0` + /// @invariant if :expr:`has_mutable_data() == true` then :expr:`data == mutable_data` const T* get_data() const noexcept { return data_ptr_; } + /// Returns whether array contains :expr:`mutable_data` or not + /// + /// @invariant :expr:`mutable_data != nullptr` if this returns `true` and :expr:`count > 0` bool has_mutable_data() const noexcept { return mutable_data_ptr_ != nullptr; } + + /// Returns mutable_data, if array contains it. Otherwise, allocates a + /// memory block for mutable data and fills it with the data stored at :expr:`data`. + /// Creates the ownership structure for allocated memory block and stores + /// the pointer. + /// + /// @post :expr:`has_mutable_data() == true` array& need_mutable_data() { impl_->need_mutable_data(detail::default_host_policy{}, detail::host_allocator{}); update_data(impl_->get_mutable_data(), impl_->get_count()); @@ -195,6 +358,15 @@ class array { } #ifdef ONEDAL_DATA_PARALLEL + /// Returns mutable_data, if array contains it. Otherwise, allocates a + /// memory block for mutable data and fills it with the data stored at :expr:`data`. + /// Creates the ownership structure for allocated memory block and stores + /// the pointer. + /// + /// @param queue The SYCL* queue object. + /// @param alloc The kind of USM to be allocated + /// + /// @post :expr:`has_mutable_data() == true` array& need_mutable_data(sycl::queue& queue, const sycl::usm::alloc& alloc = sycl::usm::alloc::shared) { impl_->need_mutable_data(detail::data_parallel_policy{ queue }, @@ -204,26 +376,43 @@ class array { } #endif + /// The number of elements of type $T$ in a memory block std::int64_t get_count() const noexcept { return count_; } + /// The size of memory block in bytes + /// @invariant :expr:`size == count * sizeof(T)` std::int64_t get_size() const noexcept { return count_ * sizeof(T); } + /// Resets ownership structure pointer to ``nullptr``, + /// sets :expr:`count` to zero, :expr:`data` and :expr:`mutable_data` to :expr:`nullptr`. void reset() { impl_->reset(); const T* null_data = nullptr; update_data(null_data, 0); } + /// Allocates a new memory block for mutable data, does not initialize it, + /// creates ownership structure for this block, assigns the structure inside the array. + /// The array owns allocated memory block. + /// + /// @param count The number of elements of type $Data$ to allocate memory for. void reset(std::int64_t count) { impl_->reset(detail::default_host_policy{}, count, detail::host_allocator{}); update_data(impl_->get_mutable_data(), count); } #ifdef ONEDAL_DATA_PARALLEL + /// Allocates a new memory block for mutable data, does not initialize it, + /// creates ownership structure for this block, assigns the structure inside the array. + /// The array owns allocated memory block. + /// + /// @param queue The SYCL* queue object. + /// @param count The number of elements of type $T$ to allocate memory for. + /// @param alloc The kind of USM to be allocated void reset(const sycl::queue& queue, std::int64_t count, const sycl::usm::alloc& alloc = sycl::usm::alloc::shared) { @@ -234,6 +423,16 @@ class array { } #endif + /// Creates the ownership structure for memory block of externally-allocated mutable data, + /// assigns input $deleter$ object to it, + /// sets :expr:`data` and :expr:`mutable_data` pointers to this block. + /// + /// @tparam Deleter The type of a deleter used to free the $data$. + /// The deleter implements ``void operator()(Data*)`` member function. + /// + /// @param data The mutable memory block pointer to be assigned inside the array + /// @param count The number of elements of type $Data$ into the block + /// @param deleter The object used to free $data$. template void reset(T* data, std::int64_t count, Deleter&& deleter) { // TODO: check input parameters @@ -241,6 +440,16 @@ class array { update_data(data, count); } + /// Creates the ownership structure for memory block of externally-allocated immutable data, + /// assigns input $deleter$ object to it, + /// sets :expr:`data` pointer to this block. + /// + /// @tparam ConstDeleter The type of a deleter used to free. + /// The deleter implements `void operator()(const Data*)`` member function. + /// + /// @param data The immutable memory block pointer to be assigned inside the array + /// @param count The number of elements of type $Data$ into the block + /// @param deleter The object used to free $data$. template void reset(const T* data, std::int64_t count, ConstDeleter&& deleter) { // TODO: check input parameters @@ -259,18 +468,40 @@ class array { } #endif + /// Initializes :expr:`data` and :expr:`mutable_data` with data pointer, + /// :expr:`count` with input $count$ value, initializes + /// the pointer to ownership structure with the one from ref. Array + /// returns $data$ pointer as its mutable block. + + /// @tparam ref The type of elements in the referenced array. + /// + /// @param ref The array which is used to share ownership structure with current one. + /// @param data Mutable unmanaged pointer to be assigned to the array. + /// @param count The number of elements of type $T$ in the $data$. template void reset(const array& ref, T* data, std::int64_t count) { impl_->reset(*ref.impl_, data, count); update_data(data, count); } + /// Initializes :expr:`data` with data pointer, + /// :expr:`count` with input $count$ value, initializes + /// the pointer to ownership structure with the one from ref. Array + /// returns $data$ pointer as its immutable block. + /// + /// @tparam ref The type of elements in the referenced array. + /// + /// @param ref The array which is used to share ownership structure with current one. + /// @param data Immutable unmanaged pointer to be assigned to the array. + /// @param count The number of elements of type $T$ in the $data$. template void reset(const array& ref, const T* data, std::int64_t count) { impl_->reset(*ref.impl_, data, count); update_data(data, count); } + /// Provides a read-only access to the elements of array. + /// Does not perform boundary checks. const T& operator[](std::int64_t index) const noexcept { // TODO: add asserts on data_ptr_ return data_ptr_[index]; diff --git a/cpp/oneapi/dal/table/column_accessor.hpp b/cpp/oneapi/dal/table/column_accessor.hpp index 00b493ef36a..a571986f330 100644 --- a/cpp/oneapi/dal/table/column_accessor.hpp +++ b/cpp/oneapi/dal/table/column_accessor.hpp @@ -22,6 +22,9 @@ namespace oneapi::dal { namespace v1 { +/// @tparam T The type of data values in blocks returned by the accessor. +/// Should be const-qualified for read-only access. +/// An accessor supports at least :expr:`float`, :expr:`double`, and :expr:`std::int32_t` types of $T$. template class column_accessor : private detail::accessor_base { using base = detail::accessor_base; @@ -31,6 +34,10 @@ class column_accessor : private detail::accessor_base || @@ -46,6 +53,19 @@ class column_accessor : private detail::accessor_base pull(sycl::queue& queue, std::int64_t column_index, const range& rows = { 0, -1 }, @@ -64,6 +84,22 @@ class column_accessor : private detail::accessor_base& block, std::int64_t column_index, diff --git a/cpp/oneapi/dal/table/common.hpp b/cpp/oneapi/dal/table/common.hpp index 827ac55886e..7578f32ca95 100644 --- a/cpp/oneapi/dal/table/common.hpp +++ b/cpp/oneapi/dal/table/common.hpp @@ -62,11 +62,26 @@ class ONEDAL_EXPORT table_metadata { using pimpl = detail::pimpl; public: + /// Creates the metadata instance without information about the features. + /// The :expr:`feature_count` sshould be set to zero. + /// The :expr:`data_type` and :expr:`feature_type` properties should not be initialized. table_metadata(); + + /// Creates the metadata instance from external information about the data types and the + /// feature types. + /// @param dtypes The data types of the features. Assigned into the :expr:`data_type` property. + /// @param ftypes The feature types. Assigned into the :expr:`feature_type` property. + /// @pre :expr:`dtypes.get_count() == ftypes.get_count()` table_metadata(const array& dtypes, const array& ftypes); + /// The number of features that metadata contains information about + /// @pre :expr:`feature_count >= 0` std::int64_t get_feature_count() const; + + /// Feature types in the metadata object. Should be within the range ``[0, feature_count)`` const feature_type& get_feature_type(std::int64_t feature_index) const; + + /// Data types of the features in the metadata object. Should be within the range ``[0, feature_count)`` const data_type& get_data_type(std::int64_t feature_index) const; private: @@ -81,8 +96,15 @@ class ONEDAL_EXPORT table { using pimpl = detail::pimpl; public: + /// An empty table constructor: creates the table instance with zero number of rows and columns. + /// Implementation is set to the special "empty" object that returns all the property values + /// set to default (see Properties section). table(); + + /// Creates a new table instance that shares the implementation with another one. table(const table&) = default; + + /// Creates a new table instance and moves implementation from another one into it. table(table&&); template (impl))); } + /// Replaces the implementation by another one. table& operator=(const table&) = default; + + /// Swaps the implementation of this object and another one. table& operator=(table&&); + /// Indicates whether a table contains non-zero number of rows and columns. bool has_data() const noexcept; + + /// The number of columns in the table. + /// @remark default = 0 std::int64_t get_column_count() const; + + /// The number of rows in the table. + /// @remark default = 0 std::int64_t get_row_count() const; + + /// The metadata object that holds additional information + /// about the data within the table. + /// @remark default = table_metadata() const table_metadata& get_metadata() const; + + /// The runtime id of the table type. + /// Each table sub-type has its unique ``kind``. + /// An empty table (see the default constructor) has a unique ``kind`` value as well. + /// @remark default = empty_table_kind std::int64_t get_kind() const; + + /// The layout of the data within the table + /// @remark default = data_layout::unknown data_layout get_data_layout() const; protected: diff --git a/cpp/oneapi/dal/table/homogen.hpp b/cpp/oneapi/dal/table/homogen.hpp index 40f55fa9f0d..8bcb59a3be1 100644 --- a/cpp/oneapi/dal/table/homogen.hpp +++ b/cpp/oneapi/dal/table/homogen.hpp @@ -53,8 +53,24 @@ class ONEDAL_EXPORT homogen_table : public table { using pimpl = detail::pimpl; public: + /// Returns the unique id of ``homogen_table`` class. static std::int64_t kind(); + /// Creates a new ``homogen_table`` instance from externally-defined data block. Table + /// object refers to the data but does not own it. The responsibility to + /// free the data remains on the user side. + /// The :expr:`data` should point to the ``data_pointer`` memory block. + /// + /// @tparam Data The type of elements in the data block that will be stored into the table. + /// The table initializes data types of metadata with this data type. + /// The feature types should be set to default values for $Data$ type: contiguous for floating-point, + /// ordinal for integer types. + /// The $Data$ type should be at least :expr:`float`, :expr:`double` or :expr:`std::int32_t`. + /// @param data_pointer The pointer to a homogeneous data block. + /// @param row_count The number of rows in the table. + /// @param column_count The number of columns in the table. + /// @param layout The layout of the data. Should be ``data_layout::row_major`` or + /// ``data_layout::column_major``. template static homogen_table wrap(const Data* data_pointer, std::int64_t row_count, @@ -68,6 +84,23 @@ class ONEDAL_EXPORT homogen_table : public table { } #ifdef ONEDAL_DATA_PARALLEL + /// Creates a new ``homogen_table`` instance from externally-defined data block. Table + /// object refers to the data but does not own it. The responsibility to + /// free the data remains on the user side. + /// The :expr:`data` should point to the ``data_pointer`` memory block. + /// + /// @tparam Data The type of elements in the data block that will be stored into the table. + /// The table initializes data types of metadata with this data type. + /// The feature types should be set to default values for $Data$ type: contiguous for floating-point, + /// ordinal for integer types. + /// The $Data$ type should be at least :expr:`float`, :expr:`double` or :expr:`std::int32_t`. + /// @param queue The SYCL* queue object + /// @param data_pointer The pointer to a homogeneous data block. + /// @param row_count The number of rows in the table. + /// @param column_count The number of columns in the table. + /// @param dependencies Events indicating availability of the $data$ for reading or writing. + /// @param layout The layout of the data. Should be ``data_layout::row_major`` or + /// ``data_layout::column_major``. template static homogen_table wrap(const sycl::queue& queue, const Data* data_pointer, @@ -86,6 +119,9 @@ class ONEDAL_EXPORT homogen_table : public table { #endif public: + /// Creates a new ``homogen_table`` instance with zero number of rows and columns. + /// The :expr:`kind` is set to``homogen_table::kind()``. + /// All the properties should be set to default values (see the Properties section). homogen_table(); template (impl)); } + /// Creates a new ``homogen_table`` instance from externally-defined data block. + /// Table object owns the data pointer. + /// The :expr:`data` should point to the ``data_pointer`` memory block. + /// + /// @tparam Data The type of elements in the data block that will be stored into the table. + /// The $Data$ type should be at least :expr:`float`, :expr:`double` or :expr:`std::int32_t`. + /// @tparam ConstDeleter The type of a deleter called on ``data_pointer`` when + /// the last table that refers it is out of the scope. + /// + /// @param data_pointer The pointer to a homogeneous data block. + /// @param row_count The number of rows in the table. + /// @param column_count The number of columns in the table. + /// @param data_deleter The deleter that is called on the ``data_pointer`` when the last table that refers it + /// is out of the scope. + /// @param layout The layout of the data. Should be ``data_layout::row_major`` or + /// ``data_layout::column_major``. template homogen_table(const Data* data_pointer, std::int64_t row_count, @@ -111,6 +163,24 @@ class ONEDAL_EXPORT homogen_table : public table { } #ifdef ONEDAL_DATA_PARALLEL + /// Creates a new ``homogen_table`` instance from externally-defined data block. + /// Table object owns the data pointer. + /// The :expr:`data` should point to the ``data_pointer`` memory block. + /// + /// @tparam Data The type of elements in the data block that will be stored into the table. + /// The $Data$ type should be at least :expr:`float`, :expr:`double` or :expr:`std::int32_t`. + /// @tparam ConstDeleter The type of a deleter called on ``data_pointer`` when + /// the last table that refers it is out of the scope. + /// + /// @param queue The SYCL* queue object + /// @param data_pointer The pointer to a homogeneous data block. + /// @param row_count The number of rows in the table. + /// @param column_count The number of columns in the table. + /// @param data_deleter The deleter that is called on the ``data_pointer`` when the last table that refers it + /// is out of the scope. + /// @param dependencies Events indicating availability of the $data$ for reading or writing. + /// @param layout The layout of the data. Should be ``data_layout::row_major`` or + /// ``data_layout::column_major``. template homogen_table(const sycl::queue& queue, const Data* data_pointer, @@ -129,13 +199,18 @@ class ONEDAL_EXPORT homogen_table : public table { } #endif + /// Returns the :expr:`data` pointer cast to the $Data$ type. No checks are + /// performed that this type is the actual type of the data within the table. template const Data* get_data() const { return reinterpret_cast(this->get_data()); } + /// The pointer to the data block within the table. + /// Should be equal to ``nullptr`` when :expr:`row_count == 0` and :expr:`column_count == 0`. const void* get_data() const; + /// The unique id of the homogen table type. std::int64_t get_kind() const { return kind(); } diff --git a/cpp/oneapi/dal/table/row_accessor.hpp b/cpp/oneapi/dal/table/row_accessor.hpp index d1cbe50fe9d..a65fb1f7204 100644 --- a/cpp/oneapi/dal/table/row_accessor.hpp +++ b/cpp/oneapi/dal/table/row_accessor.hpp @@ -22,6 +22,9 @@ namespace oneapi::dal { namespace v1 { +/// @tparam T The type of data values in blocks returned by the accessor. +/// Should be const-qualified for read-only access. +/// An accessor supports at least :expr:`float`, :expr:`double`, and :expr:`std::int32_t` types of $T$. template class row_accessor : private detail::accessor_base { using base = detail::accessor_base; @@ -30,6 +33,10 @@ class row_accessor : private detail::accessor_base { using data_t = typename base::data_t; static constexpr bool is_readonly = base::is_readonly; + /// Creates a new read-only accessor object from the table. + /// The check that the accessor supports the table kind of $obj$ is performed. + /// The reference to the $obj$ table is stored within the accessor to + /// obtain data from the table. template < typename K, typename = std::enable_if_t || @@ -45,6 +52,17 @@ class row_accessor : private detail::accessor_base { } #ifdef ONEDAL_DATA_PARALLEL + /// Provides access to the rows of the table. + /// The method returns an array that directly points to the memory within the table + /// if it is possible. In that case, the array refers to the memory as to immutable data. + /// Otherwise, the new memory block is allocated, the data from the table rows is converted + /// and copied into this block. The array refers to the block as to mutable data. + /// + /// @param[in] queue The SYCL* queue object. + /// @param[in] rows The range of rows that data is returned from the accessor. + /// @param[in] alloc The requested kind of USM in the returned block. + /// + /// @pre ``rows`` are within the range of ``[0, obj.row_count)``. array pull(sycl::queue& queue, const range& rows = { 0, -1 }, const sycl::usm::alloc& alloc = sycl::usm::alloc::shared) const { @@ -62,6 +80,20 @@ class row_accessor : private detail::accessor_base { } #ifdef ONEDAL_DATA_PARALLEL + /// Provides access to the rows of the table. + /// The method returns the :expr:`block.data` pointer. + /// + /// @param[in] queue The SYCL* queue object. + /// @param[in,out] block The block which memory is reused (if it is possible) to obtain the data from the table. + /// The block memory is reset either when + /// its size is not big enough, or when it contains immutable data, or when direct + /// memory from the table can be used. + /// If the block is reset to use a direct memory pointer from the object, + /// it refers to this pointer as to immutable memory block. + /// @param[in] rows The range of rows that data is returned from the accessor. + /// @param[in] alloc The requested kind of USM in the returned block. + /// + /// @pre ``rows`` are within the range of ``[0, obj.row_count)``. T* pull(sycl::queue& queue, array& block, const range& rows = { 0, -1 }, From 4c5c25ba75100c81e7cf66805298b7b47e31a93e Mon Sep 17 00:00:00 2001 From: Ekaterina Mekhnetsova Date: Wed, 2 Dec 2020 10:27:04 +0300 Subject: [PATCH 2/4] Removed tail spaces --- cpp/oneapi/dal/algo/kmeans/common.hpp | 4 ++-- cpp/oneapi/dal/algo/kmeans/train_types.hpp | 2 +- cpp/oneapi/dal/algo/kmeans_init/common.hpp | 2 +- cpp/oneapi/dal/algo/knn/common.hpp | 2 +- cpp/oneapi/dal/algo/pca/common.hpp | 2 +- 5 files changed, 6 insertions(+), 6 deletions(-) diff --git a/cpp/oneapi/dal/algo/kmeans/common.hpp b/cpp/oneapi/dal/algo/kmeans/common.hpp index cc2d92cbd33..02f4673f899 100644 --- a/cpp/oneapi/dal/algo/kmeans/common.hpp +++ b/cpp/oneapi/dal/algo/kmeans/common.hpp @@ -26,7 +26,7 @@ namespace v1 { /// Tag-type that parameterizes entities used for solving /// :capterm:`clustering problem `. struct clustering {}; - + /// Alias tag-type for the clustering task. using by_default = clustering; } // namespace v1 @@ -41,7 +41,7 @@ namespace v1 { /// Tag-type that denotes `Lloyd's `_ computational /// method. struct lloyd_dense {}; - + /// Alias tag-type for `Lloyd's `_ computational /// method. using by_default = lloyd_dense; diff --git a/cpp/oneapi/dal/algo/kmeans/train_types.hpp b/cpp/oneapi/dal/algo/kmeans/train_types.hpp index 3cd8f767837..ad583ea2470 100644 --- a/cpp/oneapi/dal/algo/kmeans/train_types.hpp +++ b/cpp/oneapi/dal/algo/kmeans/train_types.hpp @@ -46,7 +46,7 @@ class train_input : public base { using task_t = Task; train_input(const table& data); - + /// Creates a new instance of the class with the given :literal:`data` and /// :literal:`initial_centroids` train_input(const table& data, const table& initial_centroids); diff --git a/cpp/oneapi/dal/algo/kmeans_init/common.hpp b/cpp/oneapi/dal/algo/kmeans_init/common.hpp index e1a48270dde..7dcca1d80d3 100644 --- a/cpp/oneapi/dal/algo/kmeans_init/common.hpp +++ b/cpp/oneapi/dal/algo/kmeans_init/common.hpp @@ -25,7 +25,7 @@ namespace task { namespace v1 { /// Tag-type that parameterizes entities used for obtaining the initial K-Means centroids. struct init {}; - + /// Alias tag-type for the initialization task. using by_default = init; } // namespace v1 diff --git a/cpp/oneapi/dal/algo/knn/common.hpp b/cpp/oneapi/dal/algo/knn/common.hpp index a67f0f79624..7f7d376c214 100644 --- a/cpp/oneapi/dal/algo/knn/common.hpp +++ b/cpp/oneapi/dal/algo/knn/common.hpp @@ -40,7 +40,7 @@ namespace method { namespace v1 { /// Tag-type that denotes `k-d tree `_ computational method. struct kd_tree {}; - + /// Tag-type that denotes `brute-force `_ computational /// method. struct brute_force {}; diff --git a/cpp/oneapi/dal/algo/pca/common.hpp b/cpp/oneapi/dal/algo/pca/common.hpp index 84e28a30c9c..fc970495750 100644 --- a/cpp/oneapi/dal/algo/pca/common.hpp +++ b/cpp/oneapi/dal/algo/pca/common.hpp @@ -41,7 +41,7 @@ namespace v1 { /// Tag-type that denotes `Covariance `_ computational /// method. struct cov {}; - + /// Tag-type that denotes `SVD `_ computational method. struct svd {}; From e1110f034abbc992abb3e81af8a3710621b12d3d Mon Sep 17 00:00:00 2001 From: Ekaterina Mekhnetsova Date: Wed, 2 Dec 2020 13:28:36 +0300 Subject: [PATCH 3/4] Fix clang --- cpp/oneapi/dal/algo/kmeans/common.hpp | 22 +++++++++--------- cpp/oneapi/dal/algo/kmeans_init/common.hpp | 22 +++++++++--------- cpp/oneapi/dal/algo/knn/common.hpp | 26 ++++++++++----------- cpp/oneapi/dal/algo/pca/common.hpp | 27 +++++++++++----------- cpp/oneapi/dal/algo/pca/train_types.hpp | 1 - cpp/oneapi/dal/array.hpp | 1 - 6 files changed, 48 insertions(+), 51 deletions(-) diff --git a/cpp/oneapi/dal/algo/kmeans/common.hpp b/cpp/oneapi/dal/algo/kmeans/common.hpp index 02f4673f899..3da3b532c64 100644 --- a/cpp/oneapi/dal/algo/kmeans/common.hpp +++ b/cpp/oneapi/dal/algo/kmeans/common.hpp @@ -23,12 +23,12 @@ namespace oneapi::dal::kmeans { namespace task { namespace v1 { - /// Tag-type that parameterizes entities used for solving - /// :capterm:`clustering problem `. - struct clustering {}; +/// Tag-type that parameterizes entities used for solving +/// :capterm:`clustering problem `. +struct clustering {}; - /// Alias tag-type for the clustering task. - using by_default = clustering; +/// Alias tag-type for the clustering task. +using by_default = clustering; } // namespace v1 using v1::clustering; @@ -38,13 +38,13 @@ using v1::by_default; namespace method { namespace v1 { - /// Tag-type that denotes `Lloyd's `_ computational - /// method. - struct lloyd_dense {}; +/// Tag-type that denotes `Lloyd's `_ computational +/// method. +struct lloyd_dense {}; - /// Alias tag-type for `Lloyd's `_ computational - /// method. - using by_default = lloyd_dense; +/// Alias tag-type for `Lloyd's `_ computational +/// method. +using by_default = lloyd_dense; } // namespace v1 using v1::lloyd_dense; diff --git a/cpp/oneapi/dal/algo/kmeans_init/common.hpp b/cpp/oneapi/dal/algo/kmeans_init/common.hpp index 7dcca1d80d3..3ccbce73abe 100644 --- a/cpp/oneapi/dal/algo/kmeans_init/common.hpp +++ b/cpp/oneapi/dal/algo/kmeans_init/common.hpp @@ -23,11 +23,11 @@ namespace oneapi::dal::kmeans_init { namespace task { namespace v1 { - /// Tag-type that parameterizes entities used for obtaining the initial K-Means centroids. - struct init {}; +/// Tag-type that parameterizes entities used for obtaining the initial K-Means centroids. +struct init {}; - /// Alias tag-type for the initialization task. - using by_default = init; +/// Alias tag-type for the initialization task. +using by_default = init; } // namespace v1 using v1::init; @@ -37,13 +37,13 @@ using v1::by_default; namespace method { namespace v1 { - /// Tag-type that denotes `dense `_ - /// computational method. - struct dense {}; - struct random_dense {}; - struct plus_plus_dense {}; - struct parallel_plus_dense {}; - using by_default = dense; +/// Tag-type that denotes `dense `_ +/// computational method. +struct dense {}; +struct random_dense {}; +struct plus_plus_dense {}; +struct parallel_plus_dense {}; +using by_default = dense; } // namespace v1 using v1::dense; diff --git a/cpp/oneapi/dal/algo/knn/common.hpp b/cpp/oneapi/dal/algo/knn/common.hpp index 7f7d376c214..693da781ccb 100644 --- a/cpp/oneapi/dal/algo/knn/common.hpp +++ b/cpp/oneapi/dal/algo/knn/common.hpp @@ -23,12 +23,12 @@ namespace oneapi::dal::knn { namespace task { namespace v1 { - /// Tag-type that parameterizes entities used for solving - /// :capterm:`classification problem `. - struct classification {}; +/// Tag-type that parameterizes entities used for solving +/// :capterm:`classification problem `. +struct classification {}; - /// Alias tag-type for classification task. - using by_default = classification; +/// Alias tag-type for classification task. +using by_default = classification; } // namespace v1 using v1::classification; @@ -38,16 +38,16 @@ using v1::by_default; namespace method { namespace v1 { - /// Tag-type that denotes `k-d tree `_ computational method. - struct kd_tree {}; +/// Tag-type that denotes `k-d tree `_ computational method. +struct kd_tree {}; - /// Tag-type that denotes `brute-force `_ computational - /// method. - struct brute_force {}; +/// Tag-type that denotes `brute-force `_ computational +/// method. +struct brute_force {}; - /// Alias tag-type for `brute-force `_ computational - /// method. - using by_default = brute_force; +/// Alias tag-type for `brute-force `_ computational +/// method. +using by_default = brute_force; } // namespace v1 using v1::kd_tree; diff --git a/cpp/oneapi/dal/algo/pca/common.hpp b/cpp/oneapi/dal/algo/pca/common.hpp index fc970495750..17a18b5ec57 100644 --- a/cpp/oneapi/dal/algo/pca/common.hpp +++ b/cpp/oneapi/dal/algo/pca/common.hpp @@ -23,12 +23,12 @@ namespace oneapi::dal::pca { namespace task { namespace v1 { - /// Tag-type that parameterizes entities used for solving - /// :capterm:`dimensionality reduction problem `. - struct dim_reduction {}; +/// Tag-type that parameterizes entities used for solving +/// :capterm:`dimensionality reduction problem `. +struct dim_reduction {}; - /// Alias tag-type for dimensionality reduction task. - using by_default = dim_reduction; +/// Alias tag-type for dimensionality reduction task. +using by_default = dim_reduction; } // namespace v1 using v1::dim_reduction; @@ -38,16 +38,16 @@ using v1::by_default; namespace method { namespace v1 { - /// Tag-type that denotes `Covariance `_ computational - /// method. - struct cov {}; +/// Tag-type that denotes `Covariance `_ computational +/// method. +struct cov {}; - /// Tag-type that denotes `SVD `_ computational method. - struct svd {}; +/// Tag-type that denotes `SVD `_ computational method. +struct svd {}; - /// Alias tag-type for `Covariance `_ computational - /// method. - using by_default = cov; +/// Alias tag-type for `Covariance `_ computational +/// method. +using by_default = cov; } // namespace v1 using v1::cov; @@ -143,7 +143,6 @@ class descriptor : public detail::descriptor_base { using method_t = Method; using task_t = Task; - /// Creates a new instance of the class with the given :literal:`component_count` /// property value explicit descriptor(std::int64_t component_count = 0) { diff --git a/cpp/oneapi/dal/algo/pca/train_types.hpp b/cpp/oneapi/dal/algo/pca/train_types.hpp index 42f2073dbb4..c92b579e379 100644 --- a/cpp/oneapi/dal/algo/pca/train_types.hpp +++ b/cpp/oneapi/dal/algo/pca/train_types.hpp @@ -78,7 +78,6 @@ class train_result { /// Creates a new instance of the class with the default property values. train_result(); - /// An $r \\times p$ table with the eigenvectors. Each row contains one /// eigenvector. /// @remark default = table{} diff --git a/cpp/oneapi/dal/array.hpp b/cpp/oneapi/dal/array.hpp index d72c4f750b8..1882c4770c8 100644 --- a/cpp/oneapi/dal/array.hpp +++ b/cpp/oneapi/dal/array.hpp @@ -344,7 +344,6 @@ class array { return mutable_data_ptr_ != nullptr; } - /// Returns mutable_data, if array contains it. Otherwise, allocates a /// memory block for mutable data and fills it with the data stored at :expr:`data`. /// Creates the ownership structure for allocated memory block and stores From bf9738ad3c04fabc48670c467c73519c3467ea05 Mon Sep 17 00:00:00 2001 From: Ekaterina Mekhnetsova Date: Tue, 8 Dec 2020 14:47:53 +0300 Subject: [PATCH 4/4] Addressed comments --- .ci/pipeline/docs.yml | 2 + cpp/oneapi/dal/algo/kmeans/common.hpp | 6 +- cpp/oneapi/dal/algo/kmeans/infer_types.hpp | 2 +- cpp/oneapi/dal/algo/kmeans/train_types.hpp | 2 +- cpp/oneapi/dal/algo/kmeans_init/common.hpp | 2 +- cpp/oneapi/dal/algo/knn/common.hpp | 4 +- cpp/oneapi/dal/algo/knn/infer_types.hpp | 2 +- cpp/oneapi/dal/algo/knn/train_types.hpp | 6 +- cpp/oneapi/dal/algo/pca/common.hpp | 2 +- cpp/oneapi/dal/algo/pca/infer_types.hpp | 2 +- cpp/oneapi/dal/algo/pca/train_types.hpp | 6 +- cpp/oneapi/dal/array.hpp | 112 ++++++++++----------- cpp/oneapi/dal/table/column_accessor.hpp | 10 +- cpp/oneapi/dal/table/homogen.hpp | 18 ++-- cpp/oneapi/dal/table/row_accessor.hpp | 6 +- 15 files changed, 92 insertions(+), 90 deletions(-) diff --git a/.ci/pipeline/docs.yml b/.ci/pipeline/docs.yml index 08ddea7d8d7..d4e3899c97d 100644 --- a/.ci/pipeline/docs.yml +++ b/.ci/pipeline/docs.yml @@ -7,6 +7,7 @@ trigger: paths: include: - cpp/daal/include + - cpp/oneapi - docs - examples @@ -19,6 +20,7 @@ pr: paths: include: - cpp/daal/include + - cpp/oneapi - docs - examples diff --git a/cpp/oneapi/dal/algo/kmeans/common.hpp b/cpp/oneapi/dal/algo/kmeans/common.hpp index 3da3b532c64..c1784373706 100644 --- a/cpp/oneapi/dal/algo/kmeans/common.hpp +++ b/cpp/oneapi/dal/algo/kmeans/common.hpp @@ -83,12 +83,12 @@ class descriptor_base : public base { descriptor_base(); - /// The number of clusters $k$ + /// The number of clusters k /// @invariant :expr:`cluster_count > 0` /// @remark default = 2 std::int64_t get_cluster_count() const; - /// The maximum number of iterations $T$ + /// The maximum number of iterations :literal:`T` /// @invariant :expr:`max_iteration_count >= 0` /// @remark default = 100 std::int64_t get_max_iteration_count() const; @@ -188,7 +188,7 @@ class model : public base { return *this; } - /// Number of clusters $k$ in the trained model. + /// Number of clusters k in the trained model. /// @invariant :expr:`cluster_count == centroids.row_count` /// @remark default = 0 std::int64_t get_cluster_count() const; diff --git a/cpp/oneapi/dal/algo/kmeans/infer_types.hpp b/cpp/oneapi/dal/algo/kmeans/infer_types.hpp index 822947d6af3..be3204c36ab 100644 --- a/cpp/oneapi/dal/algo/kmeans/infer_types.hpp +++ b/cpp/oneapi/dal/algo/kmeans/infer_types.hpp @@ -97,7 +97,7 @@ class infer_result { return *this; } - /// The value of the objective function $\\Phi_X(C)$, where $C$ is + /// The value of the objective function $\\Phi_X(C)$, where C is /// defined by the corresponding :expr:`infer_input::model::centroids`. /// @invariant :expr:`objective_function_value >= 0.0` /// @remark default = 0.0 diff --git a/cpp/oneapi/dal/algo/kmeans/train_types.hpp b/cpp/oneapi/dal/algo/kmeans/train_types.hpp index ad583ea2470..ade44d09007 100644 --- a/cpp/oneapi/dal/algo/kmeans/train_types.hpp +++ b/cpp/oneapi/dal/algo/kmeans/train_types.hpp @@ -118,7 +118,7 @@ class train_result { return *this; } - /// The value of the objective function $\\Phi_X(C)$, where $C$ is + /// The value of the objective function $\\Phi_X(C)$, where C is /// :expr:`model.centroids` (see :expr:`kmeans::model::centroids`). /// @invariant :expr:`objective_function_value >= 0.0` double get_objective_function_value() const; diff --git a/cpp/oneapi/dal/algo/kmeans_init/common.hpp b/cpp/oneapi/dal/algo/kmeans_init/common.hpp index 3ccbce73abe..fcdbac0cca3 100644 --- a/cpp/oneapi/dal/algo/kmeans_init/common.hpp +++ b/cpp/oneapi/dal/algo/kmeans_init/common.hpp @@ -86,7 +86,7 @@ class descriptor_base : public base { descriptor_base(); - /// The number of clusters $k$ + /// The number of clusters k /// @invariant :expr:`cluster_count > 0` /// @remark default = 2 std::int64_t get_cluster_count() const; diff --git a/cpp/oneapi/dal/algo/knn/common.hpp b/cpp/oneapi/dal/algo/knn/common.hpp index 693da781ccb..c3df0bdd3e7 100644 --- a/cpp/oneapi/dal/algo/knn/common.hpp +++ b/cpp/oneapi/dal/algo/knn/common.hpp @@ -87,11 +87,11 @@ class descriptor_base : public base { descriptor_base(); - /// The number of classes $c$ + /// The number of classes c /// @invariant :expr:`class_count > 1` std::int64_t get_class_count() const; - /// The number of neighbors $k$ + /// The number of neighbors k /// @invariant :expr:`neighbor_count > 0` std::int64_t get_neighbor_count() const; diff --git a/cpp/oneapi/dal/algo/knn/infer_types.hpp b/cpp/oneapi/dal/algo/knn/infer_types.hpp index 68c0af09ebc..b192897ca39 100644 --- a/cpp/oneapi/dal/algo/knn/infer_types.hpp +++ b/cpp/oneapi/dal/algo/knn/infer_types.hpp @@ -58,7 +58,7 @@ class infer_input : public base { return *this; } - /// The trained $k$-NN model + /// The trained k-NN model /// @remark default = model{} const model& get_model() const; diff --git a/cpp/oneapi/dal/algo/knn/train_types.hpp b/cpp/oneapi/dal/algo/knn/train_types.hpp index e5f5f911153..dcfc9418bf4 100644 --- a/cpp/oneapi/dal/algo/knn/train_types.hpp +++ b/cpp/oneapi/dal/algo/knn/train_types.hpp @@ -49,7 +49,7 @@ class train_input : public base { /// and :literal:`labels` property values train_input(const table& data, const table& labels); - /// The training set $X$ + /// The training set X /// @remark default = table{} const table& get_data() const; @@ -58,7 +58,7 @@ class train_input : public base { return *this; } - /// Vector of labels $y$ for the training set $X$ + /// Vector of labels y for the training set X /// @remark default = table{} const table& get_labels() const; @@ -87,7 +87,7 @@ class train_result { /// Creates a new instance of the class with the default property values. train_result(); - /// The trained $k$-NN model + /// The trained k-NN model /// @remark default = model{} const model& get_model() const; diff --git a/cpp/oneapi/dal/algo/pca/common.hpp b/cpp/oneapi/dal/algo/pca/common.hpp index 17a18b5ec57..7999c545337 100644 --- a/cpp/oneapi/dal/algo/pca/common.hpp +++ b/cpp/oneapi/dal/algo/pca/common.hpp @@ -87,7 +87,7 @@ class descriptor_base : public base { descriptor_base(); - /// The number of principal components $r$. If it is zero, the algorithm + /// The number of principal components :literal:`r`. If it is zero, the algorithm /// computes the eigenvectors for all features, $r = p$. /// @remark default = 0 /// @invariant :expr:`component_count >= 0` diff --git a/cpp/oneapi/dal/algo/pca/infer_types.hpp b/cpp/oneapi/dal/algo/pca/infer_types.hpp index 2005248a0af..03bb2553b75 100644 --- a/cpp/oneapi/dal/algo/pca/infer_types.hpp +++ b/cpp/oneapi/dal/algo/pca/infer_types.hpp @@ -87,7 +87,7 @@ class infer_result { /// Creates a new instance of the class with the default property values. infer_result(); - /// An $n \\times r$ table that contains data projected to the $r$ + /// An $n \\times r$ table that contains data projected to the :literal:`r` /// principal components. /// @remark default = table{} const table& get_transformed_data() const; diff --git a/cpp/oneapi/dal/algo/pca/train_types.hpp b/cpp/oneapi/dal/algo/pca/train_types.hpp index c92b579e379..24d20edf732 100644 --- a/cpp/oneapi/dal/algo/pca/train_types.hpp +++ b/cpp/oneapi/dal/algo/pca/train_types.hpp @@ -94,7 +94,7 @@ class train_result { } /// A $1 \\times r$ table that contains the eigenvalues for for the first - /// $r$ features. + /// :literal:`r` features. /// @remark default = table{} const table& get_eigenvalues() const; @@ -103,7 +103,7 @@ class train_result { return *this; } - /// A $1 \\times r$ table that contains the variances for the first $r$ + /// A $1 \\times r$ table that contains the variances for the first :literal:`r` /// features. /// @remark default = table{} const table& get_variances() const; @@ -113,7 +113,7 @@ class train_result { return *this; } - /// A $1 \\times r$ table that contains the mean values for the first $r$ + /// A $1 \\times r$ table that contains the mean values for the first :literal:`r` /// features. /// @remark default = table{} const table& get_means() const; diff --git a/cpp/oneapi/dal/array.hpp b/cpp/oneapi/dal/array.hpp index 1882c4770c8..a759a309e5a 100644 --- a/cpp/oneapi/dal/array.hpp +++ b/cpp/oneapi/dal/array.hpp @@ -25,9 +25,9 @@ namespace oneapi::dal { namespace v1 { /// @tparam T The type of the memory block elements within the array. -/// $T$ can represent any type. +/// :literal:`T` can represent any type. /// -/// @pre $T$ cannot be const-qualified. +/// @pre :literal:`T` cannot be const-qualified. template class array { static_assert(!std::is_const_v, "array class cannot have const-qualified type of data"); @@ -45,7 +45,7 @@ class array { /// creates a new array instance by passing a pointer to the memory block. /// The array owns the memory block (for details, see :txtref:`data_ownership_requirements`). /// - /// @param count The number of elements of type $Data$ to allocate memory for. + /// @param count The number of elements of type :literal:`Data` to allocate memory for. /// @pre :expr:`count > 0` static array empty(std::int64_t count) { return array{ @@ -60,7 +60,7 @@ class array { /// The array owns the memory block (for details, see :txtref:`data_ownership_requirements`). /// /// @param queue The SYCL* queue object. - /// @param count The number of elements of type $T$ to allocate memory for. + /// @param count The number of elements of type :literal:`T` to allocate memory for. /// @param alloc The kind of USM to be allocated. /// @pre :expr:`count > 0` static array empty(const sycl::queue& queue, @@ -76,9 +76,9 @@ class array { /// creates a new array instance by passing a pointer to the memory block. /// The array owns the memory block (for details, see :txtref:`data_ownership_requirements`). /// - /// @tparam Element The type from which array elements of type $T$ can be constructed. + /// @tparam Element The type from which array elements of type :literal:`T` can be constructed. /// - /// @param count The number of elements of type $T$ to allocate memory for. + /// @param count The number of elements of type :literal:`T` to allocate memory for. /// @param element The value that is used to fill a memory block. /// @pre :expr:`count > 0` /// @pre Elements of type ``T`` are constructible from the ``Element`` type. @@ -95,10 +95,10 @@ class array { /// creates a new array instance by passing a pointer to the memory block. /// The array owns the memory block (for details, see :txtref:`data_ownership_requirements`). /// - /// @tparam Element The type from which array elements of type $Data$ can be constructed. + /// @tparam Element The type from which array elements of type :literal:`Data` can be constructed. /// /// @param queue The SYCL* queue object. - /// @param count The number of elements of type $Data$ to allocate memory for. + /// @param count The number of elements of type :literal:`Data` to allocate memory for. /// @param element The value that is used to fill a memory block. /// @param alloc The kind of USM to be allocated. /// @pre :expr:`count > 0` @@ -119,7 +119,7 @@ class array { /// creates a new array instance by passing a pointer to the memory block. /// The array owns the memory block (for details, see :txtref:`data_ownership_requirements`). /// - /// @param count The number of elements of type $Data$ to allocate memory for. + /// @param count The number of elements of type :literal:`Data` to allocate memory for. /// @pre :expr:`count > 0` static array zeros(std::int64_t count) { // TODO: can be optimized in future @@ -135,7 +135,7 @@ class array { /// The array owns the memory block (for details, see :txtref:`data_ownership_requirements`). /// /// @param queue The SYCL* queue object. - /// @param count The number of elements of type $T$ to allocate memory for. + /// @param count The number of elements of type :literal:`T` to allocate memory for. /// @param alloc The kind of USM to be allocated. /// @pre :expr:`count > 0`s static array zeros(sycl::queue& queue, @@ -154,7 +154,7 @@ class array { /// as the array does not free it when the reference count is zero. /// /// @param data The pointer to externally-allocated memory block. - /// @param count The number of elements of type $Data$ in the memory block. + /// @param count The number of elements of type :literal:`Data` in the memory block. /// @pre :expr:`data != nullptr` /// @pre :expr:`count > 0` template @@ -169,8 +169,8 @@ class array { /// as the array does not free it when the reference count is zero. /// /// @param data The pointer to externally-allocated memory block. - /// @param count The number of elements of type $T$ in the memory block. - /// @param dependencies Events indicating availability of the $data$ for reading or writing. + /// @param count The number of elements of type :literal:`T` in the memory block. + /// @param dependencies Events indicating availability of the :literal:`Data` for reading or writing. /// @pre :expr:`data != nullptr` /// @pre :expr:`count > 0` template @@ -190,27 +190,27 @@ class array { update_data(null_data, 0); } - /// Creates a new array instance that shares an ownership with $other$ on its memory block. + /// Creates a new array instance that shares an ownership with :literal:`other` on its memory block. array(const array& a) : impl_(new impl_t(*a.impl_)) { update_data(impl_.get()); } /// Moves :expr:`data`, :expr:`mutable_data` pointers, :expr:`count`, and pointer to the ownership structure - /// in $other$ to the new array instance + /// in :literal:`other` to the new array instance array(array&& a) : impl_(std::move(a.impl_)) { update_data(impl_.get()); } /// Creates a new array instance which owns a memory block of externally-allocated mutable data. - /// The ownership structure is created for a block, the input $deleter$ + /// The ownership structure is created for a block, the input :literal:`deleter` /// is assigned to it. /// - /// @tparam Deleter The type of a deleter used to free the $data$. + /// @tparam Deleter The type of a deleter used to free the :literal:`Data`. /// The deleter provides ``void operator()(Data*)`` member function. /// /// @param data The pointer to externally-allocated memory block. - /// @param count The number of elements of type $Data$ in the memory block. - /// @param deleter The object used to free $data$. + /// @param count The number of elements of type :literal:`Data` in the memory block. + /// @param deleter The object used to free :literal:`Data`. template explicit array(T* data, std::int64_t count, Deleter&& deleter) : impl_(new impl_t(data, count, std::forward(deleter))) { @@ -218,15 +218,15 @@ class array { } /// Creates a new array instance which owns a memory block of externally-allocated immutable data. - /// The ownership structure is created for a block, the input $deleter$ + /// The ownership structure is created for a block, the input :literal:`deleter` /// is assigned to it. /// - /// @tparam ConstDeleter The type of a deleter used to free the $data$. + /// @tparam ConstDeleter The type of a deleter used to free the :literal:`Data`. /// The deleter implements ``void operator()(const Data*)`` member function. /// /// @param data The pointer to externally-allocated memory block. - /// @param count The number of elements of type $Data$ in the $data$. - /// @param deleter The object used to free $data$. + /// @param count The number of elements of type :literal:`Data` in the :literal:`Data`. + /// @param deleter The object used to free :literal:`Data`. template explicit array(const T* data, std::int64_t count, ConstDeleter&& deleter) : impl_(new impl_t(data, count, std::forward(deleter))) { @@ -235,17 +235,17 @@ class array { #ifdef ONEDAL_DATA_PARALLEL /// Creates a new array instance which owns a memory block of externally-allocated mutable data. - /// The ownership structure is created for a block, the input $deleter$ + /// The ownership structure is created for a block, the input :literal:`deleter` /// is assigned to it. /// - /// @tparam Deleter The type of a deleter used to free the $data$. + /// @tparam Deleter The type of a deleter used to free the :literal:`Data`. /// The deleter provides ``void operator()(T*)`` member function. /// /// @param queue The SYCL* queue object. /// @param data The pointer to externally-allocated memory block. - /// @param count The number of elements of type $T$ in the memory block. - /// @param deleter The object used to free $data$. - /// @param dependencies Events that indicate when $data$ becomes ready to be read or written + /// @param count The number of elements of type :literal:`T` in the memory block. + /// @param deleter The object used to free :literal:`Data`. + /// @param dependencies Events that indicate when :literal:`Data` becomes ready to be read or written template explicit array(const sycl::queue& queue, T* data, @@ -258,16 +258,16 @@ class array { } /// Creates the ownership structure for memory block of externally-allocated immutable data, - /// assigns input $deleter$ object to it, + /// assigns input :literal:`deleter` object to it, /// sets :expr:`data` pointer to this block. /// /// @tparam ConstDeleter The type of a deleter used to free. /// The deleter implements `void operator()(const T*)`` member function. /// /// @param data The immutable memory block pointer to be assigned inside the array - /// @param count The number of elements of type $T$ into the block - /// @param deleter The object used to free $data$. - /// @param dependencies Events indicating availability of the $data$ for reading or writing. + /// @param count The number of elements of type :literal:`T` into the block + /// @param deleter The object used to free :literal:`Data`. + /// @param dependencies Events indicating availability of the :literal:`Data` for reading or writing. template explicit array(const sycl::queue& queue, const T* data, @@ -280,19 +280,19 @@ class array { } #endif - /// An aliasing constructor: creates a new array instance that stores $data$ pointer, - /// assigns the pointer to the ownership structure of $ref$ to the new instance. - /// Array returns $data$ pointer as its mutable or immutable block depending - /// on the $data$ type. + /// An aliasing constructor: creates a new array instance that stores :literal:`Data` pointer, + /// assigns the pointer to the ownership structure of :literal:`ref` to the new instance. + /// Array returns :literal:`Data` pointer as its mutable or immutable block depending + /// on the :literal:`Data` type. /// /// @tparam ref The type of elements in the referenced array. - /// @tparam data Either $T$ or $const T$ type. + /// @tparam data Either :literal:`T` or $const T$ type. /// /// @param ref The array which shares ownership structure with created /// one. /// @param data Mutable or immutable unmanaged pointer hold by /// created array. - /// @param count The number of elements of type $T$ in the $data$. + /// @param count The number of elements of type :literal:`T` in the :literal:`Data`. /// /// @pre :expr:`std::is_same_v || std::is_same_v` template @@ -302,7 +302,7 @@ class array { } /// Replaces the :expr:`data`, :expr:`mutable_data` pointers, :expr:`count`, and pointer - /// to the ownership structure in the array instance by the values in $other$. + /// to the ownership structure in the array instance by the values in :literal:`other`. /// /// @post :expr:`data == other.data` /// @post :expr:`mutable_data == other.mutable_data` @@ -314,7 +314,7 @@ class array { } /// Swaps the values of :expr:`data`, :expr:`mutable_data` pointers, :expr:`count`, and pointer - /// to the ownership structure in the array instance and $other$. + /// to the ownership structure in the array instance and :literal:`other`. array operator=(array&& other) { swap(*this, other); return *this; @@ -375,7 +375,7 @@ class array { } #endif - /// The number of elements of type $T$ in a memory block + /// The number of elements of type :literal:`T` in a memory block std::int64_t get_count() const noexcept { return count_; } @@ -398,7 +398,7 @@ class array { /// creates ownership structure for this block, assigns the structure inside the array. /// The array owns allocated memory block. /// - /// @param count The number of elements of type $Data$ to allocate memory for. + /// @param count The number of elements of type :literal:`Data` to allocate memory for. void reset(std::int64_t count) { impl_->reset(detail::default_host_policy{}, count, detail::host_allocator{}); update_data(impl_->get_mutable_data(), count); @@ -410,7 +410,7 @@ class array { /// The array owns allocated memory block. /// /// @param queue The SYCL* queue object. - /// @param count The number of elements of type $T$ to allocate memory for. + /// @param count The number of elements of type :literal:`T` to allocate memory for. /// @param alloc The kind of USM to be allocated void reset(const sycl::queue& queue, std::int64_t count, @@ -423,15 +423,15 @@ class array { #endif /// Creates the ownership structure for memory block of externally-allocated mutable data, - /// assigns input $deleter$ object to it, + /// assigns input :literal:`deleter` object to it, /// sets :expr:`data` and :expr:`mutable_data` pointers to this block. /// - /// @tparam Deleter The type of a deleter used to free the $data$. + /// @tparam Deleter The type of a deleter used to free the :literal:`Data`. /// The deleter implements ``void operator()(Data*)`` member function. /// /// @param data The mutable memory block pointer to be assigned inside the array - /// @param count The number of elements of type $Data$ into the block - /// @param deleter The object used to free $data$. + /// @param count The number of elements of type :literal:`Data` into the block + /// @param deleter The object used to free :literal:`Data`. template void reset(T* data, std::int64_t count, Deleter&& deleter) { // TODO: check input parameters @@ -440,15 +440,15 @@ class array { } /// Creates the ownership structure for memory block of externally-allocated immutable data, - /// assigns input $deleter$ object to it, + /// assigns input :literal:`deleter` object to it, /// sets :expr:`data` pointer to this block. /// /// @tparam ConstDeleter The type of a deleter used to free. /// The deleter implements `void operator()(const Data*)`` member function. /// /// @param data The immutable memory block pointer to be assigned inside the array - /// @param count The number of elements of type $Data$ into the block - /// @param deleter The object used to free $data$. + /// @param count The number of elements of type :literal:`Data` into the block + /// @param deleter The object used to free :literal:`Data`. template void reset(const T* data, std::int64_t count, ConstDeleter&& deleter) { // TODO: check input parameters @@ -468,15 +468,15 @@ class array { #endif /// Initializes :expr:`data` and :expr:`mutable_data` with data pointer, - /// :expr:`count` with input $count$ value, initializes + /// :expr:`count` with input :literal:`count` value, initializes /// the pointer to ownership structure with the one from ref. Array - /// returns $data$ pointer as its mutable block. + /// returns :literal:`Data` pointer as its mutable block. /// @tparam ref The type of elements in the referenced array. /// /// @param ref The array which is used to share ownership structure with current one. /// @param data Mutable unmanaged pointer to be assigned to the array. - /// @param count The number of elements of type $T$ in the $data$. + /// @param count The number of elements of type :literal:`T` in the :literal:`Data`. template void reset(const array& ref, T* data, std::int64_t count) { impl_->reset(*ref.impl_, data, count); @@ -484,15 +484,15 @@ class array { } /// Initializes :expr:`data` with data pointer, - /// :expr:`count` with input $count$ value, initializes + /// :expr:`count` with input :literal:`count` value, initializes /// the pointer to ownership structure with the one from ref. Array - /// returns $data$ pointer as its immutable block. + /// returns :literal:`Data` pointer as its immutable block. /// /// @tparam ref The type of elements in the referenced array. /// /// @param ref The array which is used to share ownership structure with current one. /// @param data Immutable unmanaged pointer to be assigned to the array. - /// @param count The number of elements of type $T$ in the $data$. + /// @param count The number of elements of type :literal:`T` in the :literal:`Data`. template void reset(const array& ref, const T* data, std::int64_t count) { impl_->reset(*ref.impl_, data, count); diff --git a/cpp/oneapi/dal/table/column_accessor.hpp b/cpp/oneapi/dal/table/column_accessor.hpp index a571986f330..4c55e8c6134 100644 --- a/cpp/oneapi/dal/table/column_accessor.hpp +++ b/cpp/oneapi/dal/table/column_accessor.hpp @@ -24,7 +24,7 @@ namespace v1 { /// @tparam T The type of data values in blocks returned by the accessor. /// Should be const-qualified for read-only access. -/// An accessor supports at least :expr:`float`, :expr:`double`, and :expr:`std::int32_t` types of $T$. +/// An accessor supports at least :expr:`float`, :expr:`double`, and :expr:`std::int32_t` types of :literal:`T`. template class column_accessor : private detail::accessor_base { using base = detail::accessor_base; @@ -35,8 +35,8 @@ class column_accessor : private detail::accessor_base @@ -137,7 +137,7 @@ class ONEDAL_EXPORT homogen_table : public table { /// The :expr:`data` should point to the ``data_pointer`` memory block. /// /// @tparam Data The type of elements in the data block that will be stored into the table. - /// The $Data$ type should be at least :expr:`float`, :expr:`double` or :expr:`std::int32_t`. + /// The :literal:`Data` type should be at least :expr:`float`, :expr:`double` or :expr:`std::int32_t`. /// @tparam ConstDeleter The type of a deleter called on ``data_pointer`` when /// the last table that refers it is out of the scope. /// @@ -168,7 +168,7 @@ class ONEDAL_EXPORT homogen_table : public table { /// The :expr:`data` should point to the ``data_pointer`` memory block. /// /// @tparam Data The type of elements in the data block that will be stored into the table. - /// The $Data$ type should be at least :expr:`float`, :expr:`double` or :expr:`std::int32_t`. + /// The :literal:`Data` type should be at least :expr:`float`, :expr:`double` or :expr:`std::int32_t`. /// @tparam ConstDeleter The type of a deleter called on ``data_pointer`` when /// the last table that refers it is out of the scope. /// @@ -178,7 +178,7 @@ class ONEDAL_EXPORT homogen_table : public table { /// @param column_count The number of columns in the table. /// @param data_deleter The deleter that is called on the ``data_pointer`` when the last table that refers it /// is out of the scope. - /// @param dependencies Events indicating availability of the $data$ for reading or writing. + /// @param dependencies Events indicating availability of the :literal:`Data` for reading or writing. /// @param layout The layout of the data. Should be ``data_layout::row_major`` or /// ``data_layout::column_major``. template @@ -199,7 +199,7 @@ class ONEDAL_EXPORT homogen_table : public table { } #endif - /// Returns the :expr:`data` pointer cast to the $Data$ type. No checks are + /// Returns the :expr:`data` pointer cast to the :literal:`Data` type. No checks are /// performed that this type is the actual type of the data within the table. template const Data* get_data() const { diff --git a/cpp/oneapi/dal/table/row_accessor.hpp b/cpp/oneapi/dal/table/row_accessor.hpp index a65fb1f7204..306d42f45ba 100644 --- a/cpp/oneapi/dal/table/row_accessor.hpp +++ b/cpp/oneapi/dal/table/row_accessor.hpp @@ -24,7 +24,7 @@ namespace v1 { /// @tparam T The type of data values in blocks returned by the accessor. /// Should be const-qualified for read-only access. -/// An accessor supports at least :expr:`float`, :expr:`double`, and :expr:`std::int32_t` types of $T$. +/// An accessor supports at least :expr:`float`, :expr:`double`, and :expr:`std::int32_t` types of :literal:`T`. template class row_accessor : private detail::accessor_base { using base = detail::accessor_base; @@ -34,8 +34,8 @@ class row_accessor : private detail::accessor_base { static constexpr bool is_readonly = base::is_readonly; /// Creates a new read-only accessor object from the table. - /// The check that the accessor supports the table kind of $obj$ is performed. - /// The reference to the $obj$ table is stored within the accessor to + /// The check that the accessor supports the table kind of :literal:`obj` is performed. + /// The reference to the :literal:`obj` table is stored within the accessor to /// obtain data from the table. template < typename K,