Merge pull request #1054 from apslight/PriMst

[WIP]Documentation of pgr_kruskal

Author: apslight

configuration.conf

@@ -31,7 +31,7 @@ vrppdtw             | N | Y | Y
 withPoints          | Y | Y | Y
 lineGraph           | Y | Y | Y
 components          | Y | Y | Y
-prim 		    | Y | Y | Y
+mst     	    | Y | Y | Y
 #----------------------
 # SQL only directories
 #----------------------

doc/prim/CMakeLists.txt renamed to doc/mst/CMakeLists.txt

@@ -1,5 +1,7 @@
 
 SET(LOCAL_FILES
+    doc-pgr_kruskal.queries
+    pgr_kruskal.rst 
     doc-pgr_prim.queries
     pgr_prim.rst
     )

doc/mst/doc-pgr_kruskal.queries

@@ -0,0 +1,45 @@
+BEGIN;
+BEGIN
+-- q1
+SELECT * FROM pgr_kruskal(
+    'SELECT id, source, target, cost, reverse_cost 
+        FROM edge_table'
+);
+ seq | component | edge | cost | tree_cost 
+-----+-----------+------+------+-----------
+   1 |         1 |    1 |    1 |         1
+   2 |         1 |    3 |    1 |         2
+   3 |         1 |    7 |    1 |         3
+   4 |         1 |   15 |    1 |         4
+   5 |         1 |   14 |    1 |         5
+   6 |         1 |   16 |    1 |         6
+   7 |         1 |   13 |    1 |         7
+   8 |         1 |   12 |    1 |         8
+   9 |         1 |   11 |    1 |         9
+  10 |         1 |   10 |    1 |        10
+  11 |         1 |    6 |    1 |        11
+  12 |         1 |    2 |    1 |        12
+  13 |        14 |   17 |    1 |         1
+  14 |        16 |   18 |    1 |         1
+(14 rows)
+
+-- q2
+SELECT * FROM pgr_kruskal(
+    'SELECT id, source, target, cost, reverse_cost 
+         FROM edge_table WHERE id > 10'
+);
+ seq | component | edge | cost | tree_cost 
+-----+-----------+------+------+-----------
+   1 |         4 |   11 |    1 |         1
+   2 |         4 |   13 |    1 |         2
+   3 |         4 |   16 |    1 |         3
+   4 |         4 |   15 |    1 |         4
+   5 |         4 |   12 |    1 |         5
+   6 |         4 |   14 |    1 |         6
+   7 |        14 |   17 |    1 |         1
+   8 |        16 |   18 |    1 |         1
+(8 rows)
+
+-- q3
+ROLLBACK;
+ROLLBACK

doc/prim/doc-pgr_prim.queries renamed to doc/mst/doc-pgr_prim.queries

@@ -0,0 +1,146 @@
+..
+   ****************************************************************************
+    pgRouting Manual
+    Copyright(c) pgRouting Contributors
+
+    This documentation is licensed under a Creative Commons Attribution-Share
+    Alike 3.0 License: http://creativecommons.org/licenses/by-sa/3.0/
+   ****************************************************************************
+
+.. _pgr_kruskal:
+
+pgr_kruskal
+===============================================================================
+
+``pgr_kruskal`` — Returns the minimum spanning tree of graph using Kruskal algorithm.
+In particular, the Kruskal algorithm implemented by Boost.Graph.
+
+.. figure:: images/boost-inside.jpeg
+   :target: https://www.boost.org/doc/libs/1_64_0/libs/graph/doc/kruskal_min_spanning_tree.html
+
+   Boost Graph Inside
+
+Synopsis
+-------------------------------------------------------------------------------
+
+Kruskal's algorithm is a minimum-spanning-tree algorithm which finds an edge 
+of the least possible weight that connects any two trees in the forest. It is 
+a greedy algorithm in graph theory as it finds a minimum spanning tree for a 
+connected weighted undirected graph adding increasing cost arcs at each step. 
+This means it finds a subset of the edges that forms a tree that includes every 
+vertex, where the total weight of all the edges in the tree is minimized. If the 
+graph is not connected, then it finds a minimum spanning forest (a minimum 
+spanning tree for each connected component).
+
+Characteristics
+-------------------------------------------------------------------------------
+
+The main Characteristics are:
+
+  - Process is done only on edges with positive costs.
+ 
+  - It's implementation is only on undirected graph.
+  
+  - Edges are in ascending order by weight for each component.
+   
+  - Values are returned when there is a minimum spanning tree.
+
+    - When there is no edge in graph then EMPTY SET is return.
+  
+  - Running time: :math:`O(E*log E)`
+
+
+Signatures
+-------------------------------------------------------------------------------
+
+.. index::
+    single: kruskal
+
+.. code-block:: none
+
+    pgr_kruskal(edges_sql)
+
+    RETURNS SET OF (seq, component, edge, cost, tree_cost) 
+       or EMPTY SET
+
+The signature is for a **undirected** graph.
+
+:Example:
+
+.. code-block:: none
+
+    pgr_kruskal(TEXT edges_sql);
+    RETURNS SET OF (seq, component, edge, cost, tree_cost) or EMPTY SET
+
+.. literalinclude:: doc-pgr_kruskal.queries
+   :start-after: -- q1
+   :end-before: -- q2
+
+Additional example:
+
+.. literalinclude:: doc-pgr_kruskal.queries
+   :start-after: -- q2
+   :end-before: -- q3
+
+Description of the edges_sql query for kruskal functions
+...............................................................................
+
+:edges_sql: an SQL query, which should return a set of rows with the following columns:
+
+================= =================== ======== =================================================
+Column            Type                 Default  Description
+================= =================== ======== =================================================
+**id**            ``ANY-INTEGER``                Identifier of the edge.
+**source**        ``ANY-INTEGER``                Identifier of the first end point vertex of the edge.
+**target**        ``ANY-INTEGER``                Identifier of the second end point vertex of the edge.
+**cost**          ``ANY-NUMERICAL``              Weight of the edge  `(source, target)`
+
+                                                 - When negative: edge `(source, target)` does not exist, therefore it's not part of the graph.
+
+**reverse_cost**  ``ANY-NUMERICAL``       -1     Weight of the edge `(target, source)`,
+
+                                                 - When negative: edge `(target, source)` does not exist, therefore it's not part of the graph.
+
+================= =================== ======== =================================================
+
+Where:
+
+:ANY-INTEGER: SMALLINT, INTEGER, BIGINT
+:ANY-NUMERICAL: SMALLINT, INTEGER, BIGINT, REAL, FLOAT
+
+
+Description of the parameters of the signatures
+...............................................................................
+
+=================== ====================== ========= =================================================
+Parameter           Type                   Default   Description
+=================== ====================== ========= =================================================
+**edges_sql**       ``TEXT``                         SQL query as described above.
+=================== ====================== ========= =================================================
+
+Description of the return values for kruskal algorithms
+.............................................................................................................................
+
+Returns set of ``(seq, component, edge, cost, tree_cost)``
+
+===============  =========== ====================================================
+Column           Type        Description
+===============  =========== ====================================================
+**seq**          ``INT``     Sequential value starting from **1**.
+**component**    ``BIGINT``  Lowest number of the node in the component.
+**edge**         ``BIGINT``  Identifier of the edge of lightest weight.
+**cost**         ``FLOAT``   Cost to traverse of edge.
+**tree_cost**    ``FLOAT``   Aggregate cost of edges that is covered in spanning.
+===============  =========== ====================================================
+ 
+See Also
+-------------------------------------------------------------------------------
+
+* https://en.wikipedia.org/wiki/Kruskal%27s_algorithm
+* The queries use the :doc:`sampledata` network.
+
+.. rubric:: Indices and tables
+
+* :ref:`genindex`
+* :ref:`search`
+

doc/mst/pgr_kruskal.rst

@@ -1,5 +1,6 @@
 /*PGR-GNU*****************************************************************
 File: pgr_kruskal_t.h
+
 Copyright (c) 2015 Aditya Pratap Singh
 Mail: adityapratap.singh28@gmail.com
 ------
@@ -51,7 +52,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 
 typedef struct {
     int seq;
-    int sub_graph; 
+    int64_t component; 
     int64_t edge;
     double cost;
     double tree_cost;

doc/prim/pgr_prim.rst renamed to doc/mst/pgr_prim.rst

@@ -1,5 +1,6 @@
 /*PGR-GNU*****************************************************************
 File: pgr_prim_t.h
+
 Copyright (c) 2015 Aditya Pratap Singh
 Mail: adityapratap.singh28@gmail.com
 ------

include/c_types/pgr_kruskal_t.h

@@ -27,8 +27,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 
 ********************************************************************PGR-GNU*/
 
-#ifndef INCLUDE_DRIVERS_PRIM_KRUSKAL_DRIVER_H_
-#define INCLUDE_DRIVERS_PRIM_KRUSKAL_DRIVER_H_
+#ifndef INCLUDE_DRIVERS_MST_KRUSKAL_DRIVER_H_
+#define INCLUDE_DRIVERS_MST_KRUSKAL_DRIVER_H_
 #pragma once
 
 #include "c_types/pgr_edge_t.h"
@@ -52,4 +52,4 @@ extern "C" {
 }
 #endif
 
-#endif  // INCLUDE_DRIVERS_PRIM_KRUSKAL_DRIVER_H_
+#endif  // INCLUDE_DRIVERS_MST_KRUSKAL_DRIVER_H_

include/c_types/pgr_prim_t.h

@@ -27,8 +27,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 
 ********************************************************************PGR-GNU*/
 
-#ifndef INCLUDE_DRIVERS_PRIM_PRIM_DRIVER_H_
-#define INCLUDE_DRIVERS_PRIM_PRIM_DRIVER_H_
+#ifndef INCLUDE_DRIVERS_MST_PRIM_DRIVER_H_
+#define INCLUDE_DRIVERS_MST_PRIM_DRIVER_H_
 #pragma once
 
 #include "c_types/pgr_edge_t.h"
@@ -58,4 +58,4 @@ extern "C" {
 }
 #endif
 
-#endif  // INCLUDE_DRIVERS_PRIM_PRIM_DRIVER_H_
+#endif  // INCLUDE_DRIVERS_MST_PRIM_DRIVER_H_

include/drivers/prim/kruskal_driver.h renamed to include/drivers/mst/kruskal_driver.h

@@ -21,8 +21,8 @@ along with this program; if not, write to the Free Software
 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 ********************************************************************PGR-GNU*/
 
-#ifndef INCLUDE_PRIM_PGR_KRUSKAL_HPP_
-#define INCLUDE_PRIM_PGR_KRUSKAL_HPP_
+#ifndef INCLUDE_MST_PGR_KRUSKAL_HPP_
+#define INCLUDE_MST_PGR_KRUSKAL_HPP_
 #pragma once
 
 #include <boost/config.hpp>
@@ -82,7 +82,12 @@ class Pgr_kruskal {
        std::vector< std::vector< int64_t > > component;
        component.resize(num_comps);
        for (size_t i = 0; i < totalNodes; i++)
-           component[components[i]].push_back(i);
+           component[components[i]].push_back(graph[i].id);
+       for (size_t i = 0; i < num_comps; i++) {
+           std::sort(component[i].begin(), component[i].end());
+       }
+       sort(component.begin(), component.end());
+
 
        size_t size = component.size(); 
        for (size_t i = 0; i < size; i++){
@@ -94,7 +99,7 @@ class Pgr_kruskal {
 
                pgr_kruskal_t tmp; 
 
-               tmp.sub_graph = static_cast< int > (i+1);
+               tmp.component = component[i][0];;
                tmp.cost = graph[*ei].cost;  // cost
 
                auto start_node = graph.graph[source(*ei, graph.graph)].id;
@@ -126,4 +131,4 @@ Pgr_kruskal< G >::kruskal(
 } 
 
 
-#endif  // INCLUDE_PRIM_PGR_KRUSKAL_HPP_
+#endif  // INCLUDE_MST_PGR_KRUSKAL_HPP_

include/drivers/prim/prim_driver.h renamed to include/drivers/mst/prim_driver.h

@@ -21,8 +21,8 @@ along with this program; if not, write to the Free Software
 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 ********************************************************************PGR-GNU*/
 
-#ifndef INCLUDE_PRIM_PGR_PRIM_HPP_
-#define INCLUDE_PRIM_PGR_PRIM_HPP_
+#ifndef INCLUDE_MST_PGR_PRIM_HPP_
+#define INCLUDE_MST_PGR_PRIM_HPP_
 #pragma once
 
 #include <boost/config.hpp>
@@ -225,4 +225,4 @@ Pgr_prim< G >::prim(
 } 
 
 
-#endif  // INCLUDE_PRIM_PGR_PRIM_HPP_
+#endif  // INCLUDE_MST_PGR_PRIM_HPP_

include/prim/pgr_kruskal.hpp renamed to include/mst/pgr_kruskal.hpp

@@ -31,7 +31,7 @@ CREATE OR REPLACE FUNCTION pgr_kruskal(
     edges_sql TEXT,             -- Edge sql
 
     OUT seq INTEGER,            -- Seq
-    OUT sub_graph INTEGER,      -- Subgraph
+    OUT component BIGINT,       -- the lowest number of the node in the component
     OUT edge BIGINT,	     	-- Edge linked to that node
     OUT cost FLOAT,             -- Cost of edge
     OUT tree_cost FLOAT)        -- Spanning tree cost 

include/prim/pgr_prim.hpp renamed to include/mst/pgr_prim.hpp

@@ -1,4 +1,4 @@
-ADD_LIBRARY(prim OBJECT
+ADD_LIBRARY(mst OBJECT
     kruskal.c
     kruskal_driver.cpp
     prim.c

pgtap/prim/compare.test.sql renamed to pgtap/mst/compare.test.sql

@@ -49,7 +49,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 /* for functions to get edges information */
 #include "c_common/edges_input.h"
 
-#include "drivers/prim/kruskal_driver.h"  // the link to the C++ code of the function
+#include "drivers/mst/kruskal_driver.h"  // the link to the C++ code of the function
 
 PGDLLEXPORT Datum kruskal(PG_FUNCTION_ARGS);
 PG_FUNCTION_INFO_V1(kruskal);
@@ -183,7 +183,7 @@ PGDLLEXPORT Datum kruskal(PG_FUNCTION_ARGS) {
 
         // postgres starts counting from 1
         values[0] = Int32GetDatum(funcctx->call_cntr + 1); 
-        values[1] = Int32GetDatum(result_tuples[funcctx->call_cntr].sub_graph);
+        values[1] = Int64GetDatum(result_tuples[funcctx->call_cntr].component);
         values[2] = Int64GetDatum(result_tuples[funcctx->call_cntr].edge);
         values[3] = Float8GetDatum(result_tuples[funcctx->call_cntr].cost);
         values[4] = Float8GetDatum(result_tuples[funcctx->call_cntr].tree_cost);

pgtap/prim/prim-innerQuery.sql renamed to pgtap/mst/prim-innerQuery.sql

@@ -22,13 +22,13 @@ along with this program; if not, write to the Free Software
 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 ********************************************************************PGR-GNU*/
 
-#include "drivers/prim/kruskal_driver.h"
+#include "drivers/mst/kruskal_driver.h"
 
 #include <sstream>
 #include <deque>
 #include <vector>
 
-#include "prim/pgr_kruskal.hpp"
+#include "mst/pgr_kruskal.hpp"
 
 #include "cpp_common/pgr_alloc.hpp"
 #include "cpp_common/pgr_assert.h"