Docs: Subgraph Isomorphism (#2000) (#2008)

Added documentation on subgraph isomorphism algorithm.

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

@@ -22,16 +22,30 @@
 namespace oneapi::dal::preview::subgraph_isomorphism {
 
 namespace task {
+/// Tag-type that parameterizes entities that are used for Subgraph Isomorphism algorithm.
 struct compute {};
+
+/// Alias tag-type for dense computational method.
 using by_default = compute;
 } // namespace task
 
 namespace method {
+/// Tag-type that denotes fast computational method.
 struct fast {};
+
+/// Alias tag-type for fast computational method.
 using by_default = fast;
 } // namespace method
 
-enum class kind { induced, non_induced };
+/// The kinds of subgraphs to search for in a target graph.
+enum class kind {
+    /// Search for an induced subgraph isomorphic to the pattern graph. All existing and non-existing edges
+    /// in a subgraph are considered.
+    induced,
+    /// Search for a non-induced subgraph isomorphic to the pattern graph. Only existing edges
+    /// in a subgraph are considered.
+    non_induced
+};
 
 namespace detail {
 struct descriptor_tag {};
@@ -80,8 +94,15 @@ class descriptor_base : public base {
 
 /// Class for the Subgraph Isomorphism algorithm descriptor
 ///
-/// @tparam Float The data type of the result
-/// @tparam Method The algorithm method
+/// @tparam Float      The floating-point type that the algorithm uses for
+///                    intermediate computations. Can be :expr:`float` or
+///                    :expr:`double`. This parameter is not used for Subgraph Isomorphism algortihm.
+/// @tparam Method     Tag-type that specifies the implementation of the algorithm. Can
+///                    be :expr:`method::fast`.
+/// @tparam Task       Tag-type that specifies the type of the problem to solve. Can
+///                    be :expr:`task::compute`.
+/// @tparam Allocator  Custom allocator for all memory management inside the algorithm.
+///
 template <typename Float = float,
           typename Method = method::by_default,
           typename Task = task::by_default,
@@ -102,45 +123,39 @@ class descriptor : public detail::descriptor_base<Task> {
         alloc_ = allocator;
     }
 
-    /// Returns kind of subgraph isomorphism
+    /// The kind of subgraph to be isomorphic to the pattern graph. Can be :expr:`kind::induced`
+    /// or :expr:`kind::non_induced`.
     kind get_kind() const {
         return base_t::get_kind();
     }
 
-    /// Sets the type of searched subgraph in Subgraph Isomorphism computation
-    ///
-    /// @param [in] value  The begin of the row of the graph block
     auto& set_kind(kind value) {
         base_t::set_kind(value);
         return *this;
     }
 
-    /// Returns the flag if semantic search is requred in Subgraph Isomorphism computation
+    /// The flag that specifies if semantic search is required in Subgraph Isomorphism computation.
+    /// If true, vertex labels are considered.
     bool get_semantic_match() const {
         return base_t::get_semantic_match();
     }
 
-    /// Returns the flag if semantic search is requred in Subgraph Isomorphism computation
-    ///
-    /// @param [in] semantic_match The flag if semantic search is requred
     auto& set_semantic_match(bool semantic_match) {
         base_t::set_semantic_match(semantic_match);
         return *this;
     }
 
-    /// Sets the maximum number of matchings to search in Subgraph Isomorphism computation
+    /// The maximum number of matchings to search in Subgraph Isomorphism computation.
     std::int64_t get_max_match_count() const {
         return base_t::get_max_match_count();
     }
 
-    /// Sets the maximum number of matchings to search in Subgraph Isomorphism computation
-    ///
-    /// @param [in] max_match_count  The maximum number of matchings
     auto& set_max_match_count(std::int64_t max_match_count) {
         base_t::set_max_match_count(max_match_count);
         return *this;
     }
 
+    /// Returns a copy of the allocator used in the algorithm for internal memory management.
     Allocator get_allocator() const {
         return alloc_;
     }

cpp/oneapi/dal/algo/subgraph_isomorphism/graph_matching_types.hpp

@@ -25,10 +25,11 @@
 
 namespace oneapi::dal::preview::subgraph_isomorphism {
 
-/// Class for the description of the input parameters of the Subgraph Isomorphism
-/// algorithm
+/// Class for the description of the input parameters of the Subgraph Isomorphism algorithm
 ///
-/// @tparam Graph  Type of the input graph
+/// @tparam Graph  The type of the input graph.
+/// @tparam Task   Tag-type that specifies the type of the problem to solve.
+///                Can be :expr:`task::compute`.
 template <typename Graph, typename Task = task::compute>
 class graph_matching_input : public base {
     static_assert(detail::is_valid_task<Task>);
@@ -39,20 +40,22 @@ class graph_matching_input : public base {
                   "Only undirected_adjacency_vector_graph is supported.");
     /// Constructs the algorithm input initialized with the target and pattern graphs.
     ///
-    /// @param [in] target_graph  The input target (big) graph
-    /// @param [in] pattern_graph  The input patern (small) graph
-    graph_matching_input(const Graph& target_graph, const Graph& patter_graph);
+    /// @param [in] target_graph  The input target (bigger) graph
+    /// @param [in] pattern_graph  The input pattern (smaller) graph
+    graph_matching_input(const Graph& target_graph, const Graph& pattern_graph);
 
     /// Returns the constant reference to the input target graph
     const Graph& get_target_graph() const;
 
-    /// Sets the constant reference to the input target graph
+    /// Sets the target (bigger) graph to the input
+    /// @param [in] target_graph  The input target (bigger) graph
     const auto& set_target_graph(const Graph& target_graph);
 
     /// Returns the constant reference to the input pattern graph
     const Graph& get_pattern_graph() const;
 
-    /// Sets the constant reference to the input pattern graph
+    /// Sets the pattern (smaller) graph to the input
+    /// @param [in] pattern_graph  The input pattern (smaller) graph
     const auto& set_pattern_graph(const Graph& pattern_graph);
 
 private:
@@ -69,8 +72,8 @@ class graph_matching_result {
     /// Constructs the empty result
     graph_matching_result();
 
-    /// Returns the table of size [match_count x pattern_vertex_count] with matchings of pattern graph
-    /// in target graph. Each row of the table
+    /// Returns the table of size [match_count x pattern_vertex_count] with matchings
+    /// of the pattern graph in the target graph. Each row of the table
     /// contain ids of vertices in target graph sorted by pattern vertex ids.
     /// I.e. j-th element of i-th row contain id of target graph vertex which
     /// was matched with j-th vertex of pattern graph in i-th match.
@@ -83,14 +86,13 @@ class graph_matching_result {
         return get_match_count_impl();
     }
 
-    /// Sets the table with matchings of pattern graph
-    /// in target graph.
+    /// Sets the table with matchings of the pattern graph in the target graph.
     auto& set_vertex_match(const table& value) {
         set_vertex_match_impl(value);
         return *this;
     }
 
-    /// Sets the number pattern matches in the target graph.
+    /// Sets the maximum number of pattern matches in the target graph.
     auto& set_match_count(int64_t value) {
         set_match_count_impl(value);
         return *this;

docs/source/api/algorithms/graph/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.
+.. *******************************************************************************/
+
+=====
+Graph
+=====
+
+This chapter describes programming interfaces of the graph algorithms implemented in |short_name|:
+
+.. toctree::
+   :titlesonly:
+
+   subgraph-isomorphism.rst

docs/source/api/algorithms/graph/subgraph-isomorphism.rst

@@ -0,0 +1,90 @@
+.. ******************************************************************************
+.. * 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.
+.. *******************************************************************************/
+
+.. default-domain:: cpp
+
+.. _api_subgraph_isomorphism:
+
+====================
+Subgraph Isomorphism
+====================
+
+.. include::  ../../../includes/graph/subgraph-isomorphism-introduction.rst
+
+------------------------
+Mathematical formulation
+------------------------
+
+Refer to :ref:`Developer Guide: Subgraph Isomorphism <alg_subgraph_isomorphism>`.
+
+---------------------
+Programming Interface
+---------------------
+All types and functions in this section are declared in the
+``oneapi::dal::preview::subgraph_isomorphism`` namespace and
+available via inclusion of the ``oneapi/dal/algo/subgraph_isomorphism.hpp`` header file.
+
+Descriptor
+----------
+.. onedal_class:: oneapi::dal::preview::subgraph_isomorphism::descriptor
+
+Method tags
+~~~~~~~~~~~
+.. onedal_tags_namespace:: oneapi::dal::preview::subgraph_isomorphism::method
+
+Task tags
+~~~~~~~~~
+.. onedal_tags_namespace:: oneapi::dal::preview::subgraph_isomorphism::task
+
+Enum classes
+~~~~~~~~~~~~
+.. onedal_enumclass:: oneapi::dal::preview::subgraph_isomorphism::kind
+
+.. _subgraph_isomorphism_t_api:
+
+Computing :cpp:expr:`preview::graph_matching(...)`
+--------------------------------------------------
+
+.. _subgraph_isomorphism_t_api_input:
+
+Input
+~~~~~
+.. onedal_class:: oneapi::dal::preview::subgraph_isomorphism::graph_matching_input
+
+.. _subgraph_isomorphism_t_api_result:
+
+Result
+~~~~~~
+.. onedal_class:: oneapi::dal::preview::subgraph_isomorphism::graph_matching_result
+
+Operation
+~~~~~~~~~
+
+.. function:: template <typename Graph, typename Descriptor> \
+              subgraph_isomorphism::graph_matching_result preview::graph_matching( \
+                                         const Descriptor& desc, \
+                                         const Graph& target, \
+                                         const Graph& pattern)
+
+   :param desc: Subgraph Isomorphism algorithm descriptor :expr:`subgraph_isomorphism::descriptor`
+   :param target:  Target (big) graph
+   :param pattern: Pattern (small) graph
+
+--------
+Examples
+--------
+
+.. include:: ../../../includes/graph/subgraph-isomorphism-examples.rst

docs/source/api/algorithms/index.rst

@@ -28,6 +28,7 @@ Refer to :ref:`Developer Guide <dg_algorithms>` for mathematical descriptions of
    covariance/index.rst
    decomposition/index.rst
    ensembles/index.rst
+   graph/index.rst
    kernel-functions/index.rst
    nearest-neighbors/index.rst
    pairwise-distances/index.rst

docs/source/bibliography.rst

@@ -93,6 +93,12 @@ For more information about algorithms implemented in |short_name|, refer to the
    KDD '16 Proceedings of the 22nd ACM SIGKDD International
    Conference on Knowledge Discovery and Data Mining.
 
+.. [Carletti2021]
+   Carletti, Vincenzo, et al. *Parallel Subgraph Isomorphism on Multi-core Architectures: 
+   A Comparison of Four Strategies Based on Tree Search.* Joint IAPR International Workshops 
+   on Statistical Techniques in Pattern Recognition (SPR) and Structural and 
+   Syntactic Pattern Recognition (SSPR). Springer, Cham, 2021.
+
 .. [Defazio2014]
    Defazio, Aaron, Francis Bach, and Simon Lacoste-Julien.
    SAGA: A fast incremental gradient method with support for non-strongly convex composite objectives.

docs/source/conf.py

@@ -352,4 +352,10 @@
     ('cpp:identifier', 'edge_user_value_type<Graph>'),
     ('cpp:identifier', 'directed_adjacency_vector_graph'),
     ('cpp:identifier', 'undirected_adjacency_vector_graph'),
+    ('cpp:identifier', 'Allocator'),
+    ('cpp:identifier', 'Graph'),
+    ('cpp:identifier', 'subgraph_isomorphism'),
+    ('cpp:identifier', 'kind::induced'),
+    ('cpp:identifier', 'kind::non_induced'),
+    ('cpp:identifier', 'preview')
 ]

docs/source/includes/graph/subgraph-isomorphism-examples.rst

@@ -0,0 +1,23 @@
+.. ******************************************************************************
+.. * Copyright 2020-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 C++
+
+      Batch Processing:
+
+      - :ref:`cpp_subgraph_isomorphism_batch.cpp`

docs/source/includes/graph/subgraph-isomorphism-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.
+.. *******************************************************************************/
+
+Subgraph Isomorphism algorithm receives a target graph :math:`G` and a pattern graph :math:`H` as input
+and searches the target graph for subgraphs that are isomorphic to the pattern graph. The algorithm returns
+the mappings of the pattern graph vertices onto the target graph vertices.
+
+.. |si_compute|     replace::   :ref:`Computing              <subgraph_isomorphism_compute>`
+.. |si_fast|        replace::   :ref:`fast                   <subgraph_isomorphism_fast>`
+.. |si_api|         replace::   :ref:`graph_matching(...)    <subgraph_isomorphism_t_api>`
+.. |si_api_input|   replace::   :ref:`graph_matching_input   <subgraph_isomorphism_t_api_input>`
+.. |si_api_result|  replace::   :ref:`graph_matching_result  <subgraph_isomorphism_t_api_result>`
+
+================ =========================== ============ ================= =================
+ **Operation**     **Computational methods**           **Programming Interface**
+---------------- --------------------------- ------------------------------------------------
+  |si_compute|             |si_fast|            |si_api|    |si_api_input|    |si_api_result|
+================ =========================== ============ ================= =================