Cherry-pick doc commits for the release (#1999)

cpp/oneapi/dal/algo/dbscan/common.hpp

@@ -155,7 +155,7 @@ class descriptor : public detail::descriptor_base<Task> {
     using method_t = Method;
     using task_t = Task;
 
-    /// Creates a new instance of the class with the given :literals:`epsilon`, `min_observations`
+    /// Creates a new instance of the class with the given :literal:`epsilon`, :literal:`min_observations`
     explicit descriptor(double epsilon, std::int64_t min_observations) {
         set_min_observations(min_observations);
         set_epsilon(epsilon);

cpp/oneapi/dal/algo/dbscan/compute_types.hpp

@@ -116,7 +116,7 @@ class compute_result {
     }
 
     /// An $m \\times 1$ table with the indices of core observations in
-    /// the input data. $m is a number of core observations
+    /// the input data. $m$ is a number of core observations
     const table& get_core_observation_indices() const;
 
     auto& set_core_observation_indices(const table& value) {
@@ -125,7 +125,7 @@ class compute_result {
     }
 
     /// An $m \\times p$ table with the core observations in
-    /// the input data. $m is a number of core observations
+    /// the input data. $m$ is a number of core observations
     const table& get_core_observations() const;
 
     auto& set_core_observations(const table& value) {

docs/source/api/algorithms/clustering/dbscan.rst

@@ -0,0 +1,96 @@
+.. ******************************************************************************
+.. * Copyright 2021 Intel Corporation
+.. *
+.. * Licensed under the Apache License, Version 2.0 (the "License");
+.. * you may not use this file except in compliance with the License.
+.. * You may obtain a copy of the License at
+.. *
+.. *     http://www.apache.org/licenses/LICENSE-2.0
+.. *
+.. * Unless required by applicable law or agreed to in writing, software
+.. * distributed under the License is distributed on an "AS IS" BASIS,
+.. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. * See the License for the specific language governing permissions and
+.. * limitations under the License.
+.. *******************************************************************************/
+
+.. highlight:: cpp
+.. default-domain:: cpp
+
+.. _api_dbscan:
+
+======
+DBSCAN
+======
+
+.. include:: ../../../includes/clustering/dbscan-introduction.rst
+
+------------------------
+Mathematical formulation
+------------------------
+
+Refer to :ref:`Developer Guide: DBSCAN <alg_dbscan>`.
+
+---------------------
+Programming Interface
+---------------------
+
+All types and functions in this section are declared in the
+``oneapi::dal::dbscan`` namespace and are available via inclusion of the
+``oneapi/dal/algo/dbscan.hpp`` header file.
+
+Descriptor
+----------
+.. onedal_class:: oneapi::dal::dbscan::descriptor
+
+Method tags
+~~~~~~~~~~~
+.. onedal_tags_namespace:: oneapi::dal::dbscan::method
+
+Task tags
+~~~~~~~~~
+.. onedal_tags_namespace:: oneapi::dal::dbscan::task
+
+
+.. _dbscan_c_api:
+
+Computation :cpp:expr:`compute(...)`
+------------------------------------
+
+.. _dbscan_c_api_input:
+
+Input
+~~~~~
+.. onedal_class:: oneapi::dal::dbscan::compute_input
+
+.. _dbscan_c_api_result:
+
+Result
+~~~~~~
+.. onedal_class:: oneapi::dal::dbscan::compute_result
+
+Operation
+~~~~~~~~~
+
+.. function:: template <typename Descriptor> \
+              dbscan::compute_result compute(const Descriptor& desc, \
+                                         const dbscan::compute_input& input)
+
+   :param desc: DBSCAN algorithm descriptor :expr:`dbscan::descriptor`
+   :param input: Input data for the compute operation
+
+   Preconditions
+      | :expr:`input.data.has_data == true`
+      | :expr:`!input.weights.has_data || input.weights.row_count == input.data.row_count && input.weights.column_count == 1`
+
+-------------
+Usage example
+-------------
+
+.. include:: ../../../includes/clustering/dbscan-usage-examples.rst
+
+--------
+Examples
+--------
+
+.. include:: ../../../includes/clustering/dbscan-examples.rst

docs/source/api/algorithms/clustering/index.rst

@@ -23,5 +23,6 @@ This chapter describes programming interfaces of the clustering algorithms imple
 .. toctree::
    :titlesonly:
 
+   dbscan.rst
    kmeans.rst
    kmeans-init.rst

docs/source/api/index.rst

@@ -23,4 +23,5 @@ C++ API
 
    data-management/index.rst
    algorithms/index.rst
+   spmd/index.rst
 

docs/source/api/spmd/communicator.rst

@@ -0,0 +1,84 @@
+.. ******************************************************************************
+.. * Copyright 2021 Intel Corporation
+.. *
+.. * Licensed under the Apache License, Version 2.0 (the "License");
+.. * you may not use this file except in compliance with the License.
+.. * You may obtain a copy of the License at
+.. *
+.. *     http://www.apache.org/licenses/LICENSE-2.0
+.. *
+.. * Unless required by applicable law or agreed to in writing, software
+.. * distributed under the License is distributed on an "AS IS" BASIS,
+.. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. * See the License for the specific language governing permissions and
+.. * limitations under the License.
+.. *******************************************************************************/
+
+.. highlight:: cpp
+
+.. _api_communicator:
+
+=============
+Communicators
+=============
+
+.. _communicator_programming_interface:
+
+---------------------
+Programming interface
+---------------------
+
+All types and functions in this section are declared in the
+``oneapi::dal::spmd::preview`` namespace and are available via inclusion of the
+header file from specified backend.
+
+Communicator
+------------
+
+A base implementation of the :term:`communicator` concept.
+The :term:`communicator` type and all of its subtypes are :term:`reference-counted <Reference-counted object>`:
+
+1. The instance stores a pointer to the communicator implementation that holds all
+   property values and data.
+
+2. The reference count indicates how many communicator objects refer to the same implementation.
+
+3. The communicator increments the reference count
+   for it to be equal to the number of communicator objects sharing the same implementation.
+
+4. The communicator decrements the reference count when the
+   communicator goes out of the scope. If the reference count is zero, the communicator
+   frees its implementation.
+
+USM and non-USM memory usage
+----------------------------
+
+There are two types of memory access:
+
+- USM memory access (both USM and non-USM pointers can be used)
+- Host, or non-USM, memory access (only non-USM pointers can be used)
+
+Use one of the following tags to select a memory access type:
+
+device_memory_access::none
+   Assumes only non-USM pointers are used for a collective operation.
+
+device_memory_access::usm
+   Both USM and non-USM can be used. Pointer type is controlled by 
+   the use of ``sycl::queue`` object as a first parameter for collective
+   operations. The use of ``sycl::queue`` object is obligatory for USM
+   pointers.
+
+Request
+-------
+
+Request is an object to control asynchronous communication.
+
+Reducion operations
+-------------------
+
+The following reduction operations are supported:
+
+- Max
+- Min
+- Sum

docs/source/api/spmd/index.rst

@@ -0,0 +1,26 @@
+.. ******************************************************************************
+.. * Copyright 2021 Intel Corporation
+.. *
+.. * Licensed under the Apache License, Version 2.0 (the "License");
+.. * you may not use this file except in compliance with the License.
+.. * You may obtain a copy of the License at
+.. *
+.. *     http://www.apache.org/licenses/LICENSE-2.0
+.. *
+.. * Unless required by applicable law or agreed to in writing, software
+.. * distributed under the License is distributed on an "AS IS" BASIS,
+.. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. * See the License for the specific language governing permissions and
+.. * limitations under the License.
+.. *******************************************************************************/
+
+===============================================
+Distributed Model: Single Process Multiple Data
+===============================================
+
+Refer to :ref:`Developer Guide: SPMD distributed model <dg_spmd>`.
+
+.. toctree::
+
+   overview.rst
+   communicator.rst

docs/source/api/spmd/overview.rst

@@ -0,0 +1,59 @@
+.. ******************************************************************************
+.. * Copyright 2021 Intel Corporation
+.. *
+.. * Licensed under the Apache License, Version 2.0 (the "License");
+.. * you may not use this file except in compliance with the License.
+.. * You may obtain a copy of the License at
+.. *
+.. *     http://www.apache.org/licenses/LICENSE-2.0
+.. *
+.. * Unless required by applicable law or agreed to in writing, software
+.. * distributed under the License is distributed on an "AS IS" BASIS,
+.. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. * See the License for the specific language governing permissions and
+.. * limitations under the License.
+.. *******************************************************************************/
+
+.. highlight:: cpp
+.. default-domain:: cpp
+
+.. _api_spmd:
+
+======================
+Distributed SPMD model
+======================
+
+Refer to :ref:`Developer Guide: SPMD <dg_spmd>`.
+
+---------------------
+Programming interface
+---------------------
+
+All types and functions in this section are declared in the
+``oneapi::dal::spmd::preview`` namespace and are available via inclusion of the
+header file from specified backend.
+
+:term:`SPMD` distributed model consists of the following components:
+
+1. Additional ``train``, ``infer``, and ``compute`` methods that accept ``communicator`` object
+   as the first parameter. Those methods are expected to be called on all ranks to start
+   distributed simulations.
+
+2. The :term:`communicator` class that contains methods to perform collective operations among all ranks.
+
+3. Free functions to create a :term:`communicator` using a specified :term:`communicator backend`. Available backends are ``ccl``
+   and ``mpi``.
+
+-------------
+Usage example
+-------------
+
+The following listings provide a brief introduction on how to create a particular communicator.
+
+.. rubric:: MPI backend
+
+.. include:: ../../includes/spmd/mpi-comm-usage-example.rst
+
+.. rubric:: CCL backend
+
+.. include:: ../../includes/spmd/ccl-comm-usage-example.rst

docs/source/conf.py

@@ -281,6 +281,18 @@
     ('cpp:identifier', 'oneapi::dal::basic_statistics::method'),
     ('cpp:identifier', 'oneapi::dal::basic_statistics::method::v1'),
     ('cpp:identifier', 'oneapi::dal::basic_statistics::method::v1::dense'),
+    # dbscan
+    ('cpp:identifier', 'dbscan'),
+    ('cpp:identifier', 'dbscan::descriptor'),
+    ('cpp:identifier', 'dbscan::compute_result'),
+    ('cpp:identifier', 'dbscan::compute_input'),
+    ('cpp:identifier', 'oneapi::dal::dbscan'),
+    ('cpp:identifier', 'oneapi::dal::dbscan::task'),
+    ('cpp:identifier', 'oneapi::dal::dbscan::task::v1'),
+    ('cpp:identifier', 'oneapi::dal::dbscan::task::v1::compute'),
+    ('cpp:identifier', 'oneapi::dal::dbscan::method'),
+    ('cpp:identifier', 'oneapi::dal::dbscan::method::v1'),
+    ('cpp:identifier', 'oneapi::dal::dbscan::method::v1::brute_force'),
     # common for algorithms
     ('cpp:identifier', 'result'),
     # common for result options

docs/source/includes/clustering/dbscan-examples.rst

@@ -0,0 +1,35 @@
+.. ******************************************************************************
+.. * Copyright 2021 Intel Corporation
+.. *
+.. * Licensed under the Apache License, Version 2.0 (the "License");
+.. * you may not use this file except in compliance with the License.
+.. * You may obtain a copy of the License at
+.. *
+.. *     http://www.apache.org/licenses/LICENSE-2.0
+.. *
+.. * Unless required by applicable law or agreed to in writing, software
+.. * distributed under the License is distributed on an "AS IS" BASIS,
+.. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. * See the License for the specific language governing permissions and
+.. * limitations under the License.
+.. *******************************************************************************/
+
+.. tabs::
+
+  .. group-tab:: oneAPI DPC++
+
+    Batch Processing:
+
+    - :ref:`dpc_dbscan_brute_force_batch.cpp`
+
+  .. group-tab:: oneAPI C++
+
+    Batch Processing:
+
+    - :ref:`cpp_dbscan_brute_force_batch.cpp`
+
+  .. group-tab:: Python* with DPC++ support
+
+    Batch Processing:
+
+    - :daal4py_sycl_example:`dbscan_batch.py`

docs/source/includes/clustering/dbscan-introduction.rst

@@ -0,0 +1,31 @@
+.. ******************************************************************************
+.. * Copyright 2021 Intel Corporation
+.. *
+.. * Licensed under the Apache License, Version 2.0 (the "License");
+.. * you may not use this file except in compliance with the License.
+.. * You may obtain a copy of the License at
+.. *
+.. *     http://www.apache.org/licenses/LICENSE-2.0
+.. *
+.. * Unless required by applicable law or agreed to in writing, software
+.. * distributed under the License is distributed on an "AS IS" BASIS,
+.. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. * See the License for the specific language governing permissions and
+.. * limitations under the License.
+.. *******************************************************************************/
+
+Density-based spatial clustering of applications with noise (DBSCAN) is a data clustering algorithm proposed in [Ester96]_.
+It is a density-based clustering non-parametric algorithm: given a set of observations in some space,
+it groups together observations that are closely packed together (observations with many nearby neighbors),
+marking as outliers observations that lie alone in low-density regions (whose nearest neighbors are too far away).
+
+.. |c_math| replace:: :ref:`Compute <dbscan_c_math>`
+.. |c_input| replace:: :ref:`compute_input <dbscan_c_api_input>`
+.. |c_result| replace:: :ref:`compute_result <dbscan_c_api_result>`
+.. |c_op| replace:: :ref:`compute(...) <dbscan_c_api>`
+
+=============== =========================== ======== =========== ============
+ **Operation**  **Computational methods**     **Programming Interface**
+--------------- --------------------------- ---------------------------------
+   |c_math|          Default method          |c_op|   |c_input|   |c_result|
+=============== =========================== ======== =========== ============