Closes #1359 Adding pgr_dijkstra(combinations)

NEWS

@@ -1,4 +1,12 @@
 
+pgRouting 3.1.0 Release Notes
+-------------------------------------------------------------------------------
+
+*New proposed functions*
+
+* pgr_dijkstra(combinations)
+
+
 pgRouting 3.0.0 Release Notes
 -------------------------------------------------------------------------------
 

doc/dijkstra/pgr_dijkstra.rst

@@ -20,6 +20,12 @@ In particular, the Dijkstra algorithm implemented by Boost.Graph.
 
 .. rubric:: Availability
 
+* Version 3.1.0
+
+  * New **Proposed** functions:
+
+    * pgr_dijkstra(combinations sql)
+
 * Version 3.0.0
 
   * **Official** functions
@@ -96,6 +102,7 @@ Signatures
     pgr_dijkstra(edges_sql, start_vid,  end_vids [, directed])
     pgr_dijkstra(edges_sql, start_vids, end_vid  [, directed])
     pgr_dijkstra(edges_sql, start_vids, end_vids [, directed])
+    pgr_dijkstra(edges_sql, combinations_sql [, directed])
     RETURNS SET OF (seq, path_seq [, start_vid] [, end_vid], node, edge, cost, agg_cost)
     OR EMPTY SET
 
@@ -188,22 +195,42 @@ Many to Many
    :start-after: -- q5
    :end-before: -- q6
 
+.. index::
+    single: dijkstra(Combinations)
+
+Combinations SQL
+...............................................................................
+
+.. code-block:: none
+
+    pgr_dijkstra(TEXT edges_sql, TEXT combination_sql, BOOLEAN directed:=true);
+    RETURNS SET OF (seq, path_seq, start_vid, end_vid, node, edge, cost, agg_cost)
+    OR EMPTY SET
+
+:Example: Three (source, target) vertex combinaitons: (from :math:`1` to :math:`2`), (form :math:`1` to :math:`17` -no route-), and (form :math:`2` to :math:`12`) on an **undirected** graph
+
+
+.. literalinclude:: doc-pgr_dijkstra.queries
+   :start-after: -- q19
+   :end-before: -- q20
+
 Parameters
 -------------------------------------------------------------------------------
 
 .. pgr_dijkstra_parameters_start
 
-============== ================== ======== =================================================
-Parameter      Type               Default     Description
-============== ================== ======== =================================================
-**edges_sql**  ``TEXT``                    Inner SQL query as described below.
-**start_vid**  ``BIGINT``                  Identifier of the starting vertex of the path.
-**start_vids** ``ARRAY[BIGINT]``           Array of identifiers of starting vertices.
-**end_vid**    ``BIGINT``                  Identifier of the ending vertex of the path.
-**end_vids**   ``ARRAY[BIGINT]``           Array of identifiers of ending vertices.
-**directed**   ``BOOLEAN``        ``true`` - When ``true`` Graph is considered `Directed`
-                                           - When ``false`` the graph is considered as `Undirected`.
-============== ================== ======== =================================================
+====================== ================== ======== =================================================
+Parameter              Type               Default     Description
+====================== ================== ======== =================================================
+**edges_sql**          ``TEXT``                    Inner SQL query as described below.
+**start_vid**          ``BIGINT``                  Identifier of the starting vertex of the path.
+**start_vids**         ``ARRAY[BIGINT]``           Array of identifiers of starting vertices.
+**end_vid**            ``BIGINT``                  Identifier of the ending vertex of the path.
+**end_vids**           ``ARRAY[BIGINT]``           Array of identifiers of ending vertices.
+**combinations_sql**   ``TEXT``                    Inner SQL query producing pairs of starting and ending vertices as described below.
+**directed**           ``BOOLEAN``        ``true`` - When ``true`` Graph is considered `Directed`
+                                                   - When ``false`` the graph is considered as `Undirected`.
+====================== ================== ======== =================================================
 
 .. pgr_dijkstra_parameters_end
 
@@ -216,6 +243,12 @@ Inner query
     :start-after: basic_edges_sql_start
     :end-before: basic_edges_sql_end
 
+.. rubric::combinations_sql
+
+.. include:: pgRouting-concepts.rst
+    :start-after: basic_combinations_sql_start
+    :end-before: basic_combinations_sql_end
+
 Return Columns
 -------------------------------------------------------------------------------
 

doc/src/pgRouting-concepts.rst

@@ -143,6 +143,7 @@ Across this documentation, to indicate which overload we use the following terms
 * `One to Many`_
 * `Many to One`_
 * `Many to Many`_
+* `Combinations SQL`_
 
 Depending on the overload are the parameters used, keeping consistency across
 all functions.
@@ -179,6 +180,15 @@ When routing from:
 * From **many** starting vertices
 * to **many** ending vertices
 
+Combinations SQL
+...............................................................................
+
+When routing from:
+
+* From **many** different starting vertices
+* to **many** different ending vertices
+* Every tuple specifies a pair of a start vertex and an end vertex
+* Users can define the combinations as desired.
 
 
 
@@ -365,6 +375,25 @@ Where:
 
 .. points_sql_end
 
+Description of the combinations_sql query for dijkstra like functions
+...............................................................................
+
+.. basic_combinations_sql_start
+
+================= =================== ======== =================================================
+Column            Type                 Default  Description
+================= =================== ======== =================================================
+**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.
+
+================= =================== ======== =================================================
+
+Where:
+
+:ANY-INTEGER: SMALLINT, INTEGER, BIGINT
+
+.. basic_combinations_sql_end
+
 
 .. _return_values:
 

doc/src/pgRouting-introduction.rst

@@ -53,10 +53,12 @@ Cayetano Benavent,
 Gudesa Venkata Sai Akhil,
 Hang Wu,
 Maoguang Wang, Martha Vergara,
+Mahmoud SAKR, Esteban Zimanyi
 Regina Obe, Rohith Reddy,
 Sourabh Garg,
 Virginia Vergara
 
+
 And all the people that give us a little of their time making comments, finding issues, making pull requests etc.
 in any of our products: osm2pgrouting, pgRouting, pgRoutingLayer.
 
@@ -87,6 +89,7 @@ Gerald Fenoy, Gudesa Venkata Sai Akhil,
 Hang Wu,
 Jay Mahadeokar, Jinfu Leng,
 Kai Behncke, Kishore Kumar, Ko Nagase,
+Mahmoud SAKR, Esteban Zimanyi
 Manikata Kondeti, Mario Basa, Martin Wiesenhaan,  Maxim Dubinin, Maoguang Wang, Mohamed Zia, Mukul Priya,
 Razequl Islam,
 Regina Obe, Rohith Reddy,

doc/src/release_notes.rst

@@ -53,7 +53,9 @@ To see the full list of changes check the list of `Git commits <https://github.c
 pgRouting 3.1.0 Release Notes
 -------------------------------------------------------------------------------
 
-** No changes yet **
+.. rubric:: New proposed functions
+
+* pgr_dijkstra(combinations)
 
 .. _changelog_3_0_0:
 

doc/src/sampledata.rst

@@ -43,6 +43,14 @@ To be able to execute the sample queries, run the following SQL commands to crea
    :start-after: --EDGE TABLE TOPOLOGY start
    :end-before: --EDGE TABLE TOPOLOGY end
 
+.. rubric:: Combinations of start and end vertices
+
+- Used to test the combinations_sql signature in dijkstra-like functions.
+
+.. literalinclude:: ../../tools/testers/sampledata.sql
+   :start-after: --COMBINATIONS CREATE start
+   :end-before: --COMBINATIONS CREATE end
+
 .. rubric:: Points of interest
 
 - When points outside of the graph.

docqueries/dijkstra/doc-pgr_dijkstra.result

@@ -190,6 +190,32 @@ SELECT * FROM pgr_dijkstra(
   18 |        5 |        11 |       5 |    5 |   -1 |    0 |        4
 (18 rows)
 
+SELECT * FROM pgr_dijkstra(
+    'SELECT id, source, target, cost, reverse_cost FROM edge_table',
+    'SELECT * FROM (VALUES (2, 3), (2, 5), (11, 3), (11, 5)) AS combinations (source, target)'
+);
+ seq | path_seq | start_vid | end_vid | node | edge | cost | agg_cost
+-----+----------+-----------+---------+------+------+------+----------
+   1 |        1 |         2 |       3 |    2 |    4 |    1 |        0
+   2 |        2 |         2 |       3 |    5 |    8 |    1 |        1
+   3 |        3 |         2 |       3 |    6 |    9 |    1 |        2
+   4 |        4 |         2 |       3 |    9 |   16 |    1 |        3
+   5 |        5 |         2 |       3 |    4 |    3 |    1 |        4
+   6 |        6 |         2 |       3 |    3 |   -1 |    0 |        5
+   7 |        1 |         2 |       5 |    2 |    4 |    1 |        0
+   8 |        2 |         2 |       5 |    5 |   -1 |    0 |        1
+   9 |        1 |        11 |       3 |   11 |   13 |    1 |        0
+  10 |        2 |        11 |       3 |   12 |   15 |    1 |        1
+  11 |        3 |        11 |       3 |    9 |   16 |    1 |        2
+  12 |        4 |        11 |       3 |    4 |    3 |    1 |        3
+  13 |        5 |        11 |       3 |    3 |   -1 |    0 |        4
+  14 |        1 |        11 |       5 |   11 |   13 |    1 |        0
+  15 |        2 |        11 |       5 |   12 |   15 |    1 |        1
+  16 |        3 |        11 |       5 |    9 |    9 |    1 |        2
+  17 |        4 |        11 |       5 |    6 |    8 |    1 |        3
+  18 |        5 |        11 |       5 |    5 |   -1 |    0 |        4
+(18 rows)
+
 -- q8
 -- q9
 SELECT * FROM pgr_dijkstra(
@@ -284,6 +310,25 @@ SELECT * FROM pgr_dijkstra(
   10 |        3 |        11 |       5 |    5 |   -1 |    0 |        2
 (10 rows)
 
+SELECT * FROM pgr_dijkstra(
+    'SELECT id, source, target, cost, reverse_cost FROM edge_table',
+    'SELECT * FROM (VALUES (2, 3), (2, 5), (11, 3), (11, 5)) AS combinations (source, target)',
+    FALSE
+);
+ seq | path_seq | start_vid | end_vid | node | edge | cost | agg_cost
+-----+----------+-----------+---------+------+------+------+----------
+   1 |        1 |         2 |       3 |    2 |    2 |    1 |        0
+   2 |        2 |         2 |       3 |    3 |   -1 |    0 |        1
+   3 |        1 |         2 |       5 |    2 |    4 |    1 |        0
+   4 |        2 |         2 |       5 |    5 |   -1 |    0 |        1
+   5 |        1 |        11 |       3 |   11 |   11 |    1 |        0
+   6 |        2 |        11 |       3 |    6 |    5 |    1 |        1
+   7 |        3 |        11 |       3 |    3 |   -1 |    0 |        2
+   8 |        1 |        11 |       5 |   11 |   11 |    1 |        0
+   9 |        2 |        11 |       5 |    6 |    8 |    1 |        1
+  10 |        3 |        11 |       5 |    5 |   -1 |    0 |        2
+(10 rows)
+
 -- q10
 -- q11
 SELECT * FROM pgr_dijkstra(
@@ -350,6 +395,16 @@ SELECT * FROM pgr_dijkstra(
    2 |        2 |         2 |       5 |    5 |   -1 |    0 |        1
 (2 rows)
 
+SELECT * FROM pgr_dijkstra(
+    'SELECT id, source, target, cost FROM edge_table',
+    'SELECT * FROM (VALUES (2, 3), (2, 5), (11, 3), (11, 5)) AS combinations (source, target)'
+);
+ seq | path_seq | start_vid | end_vid | node | edge | cost | agg_cost
+-----+----------+-----------+---------+------+------+------+----------
+   1 |        1 |         2 |       5 |    2 |    4 |    1 |        0
+   2 |        2 |         2 |       5 |    5 |   -1 |    0 |        1
+(2 rows)
+
 -- q12
 -- q13
 SELECT * FROM pgr_dijkstra(
@@ -450,6 +505,27 @@ SELECT * FROM pgr_dijkstra(
   12 |        3 |        11 |       5 |    5 |   -1 |    0 |        2
 (12 rows)
 
+SELECT * FROM pgr_dijkstra(
+    'SELECT id, source, target, cost FROM edge_table',
+    'SELECT * FROM (VALUES (2, 3), (2, 5), (11, 3), (11, 5)) AS combinations (source, target)',
+    FALSE
+);
+ seq | path_seq | start_vid | end_vid | node | edge | cost | agg_cost
+-----+----------+-----------+---------+------+------+------+----------
+   1 |        1 |         2 |       3 |    2 |    4 |    1 |        0
+   2 |        2 |         2 |       3 |    5 |    8 |    1 |        1
+   3 |        3 |         2 |       3 |    6 |    5 |    1 |        2
+   4 |        4 |         2 |       3 |    3 |   -1 |    0 |        3
+   5 |        1 |         2 |       5 |    2 |    4 |    1 |        0
+   6 |        2 |         2 |       5 |    5 |   -1 |    0 |        1
+   7 |        1 |        11 |       3 |   11 |   11 |    1 |        0
+   8 |        2 |        11 |       3 |    6 |    5 |    1 |        1
+   9 |        3 |        11 |       3 |    3 |   -1 |    0 |        2
+  10 |        1 |        11 |       5 |   11 |   11 |    1 |        0
+  11 |        2 |        11 |       5 |    6 |    8 |    1 |        1
+  12 |        3 |        11 |       5 |    5 |   -1 |    0 |        2
+(12 rows)
+
 -- q14
 -- q15
 SELECT * FROM pgr_dijkstra(
@@ -539,6 +615,20 @@ SELECT * FROM pgr_dijkstra(
    6 |        6 |         2 |       3 |    3 |   -1 |    0 |        5
 (6 rows)
 
+SELECT * FROM pgr_dijkstra(
+    'SELECT id, source, target, cost, reverse_cost FROM edge_table',
+    'SELECT * FROM (VALUES(2, 3)) AS combinations (source, target)'
+);
+ seq | path_seq | start_vid | end_vid | node | edge | cost | agg_cost
+-----+----------+-----------+---------+------+------+------+----------
+   1 |        1 |         2 |       3 |    2 |    4 |    1 |        0
+   2 |        2 |         2 |       3 |    5 |    8 |    1 |        1
+   3 |        3 |         2 |       3 |    6 |    9 |    1 |        2
+   4 |        4 |         2 |       3 |    9 |   16 |    1 |        3
+   5 |        5 |         2 |       3 |    4 |    3 |    1 |        4
+   6 |        6 |         2 |       3 |    3 |   -1 |    0 |        5
+(6 rows)
+
 -- q16
 -- q17
 SELECT * FROM pgr_dijkstra(
@@ -585,6 +675,39 @@ SELECT * FROM pgr_dijkstra(
    2 |        2 |         2 |       3 |    3 |   -1 |    0 |        1
 (2 rows)
 
+SELECT * FROM pgr_dijkstra(
+    'SELECT id, source, target, cost, reverse_cost FROM edge_table',
+    'SELECT * FROM (VALUES(2, 3)) AS combinations (source, target)',
+    FALSE
+);
+ seq | path_seq | start_vid | end_vid | node | edge | cost | agg_cost
+-----+----------+-----------+---------+------+------+------+----------
+   1 |        1 |         2 |       3 |    2 |    2 |    1 |        0
+   2 |        2 |         2 |       3 |    3 |   -1 |    0 |        1
+(2 rows)
+
 -- q18
+-- q19
+SELECT * FROM pgr_dijkstra(
+    'SELECT id, source, target, cost, reverse_cost FROM edge_table',
+    'SELECT * FROM combinations_table',
+    FALSE
+);
+ seq | path_seq | start_vid | end_vid | node | edge | cost | agg_cost
+-----+----------+-----------+---------+------+------+------+----------
+   1 |        1 |         1 |       2 |    1 |    1 |    1 |        0
+   2 |        2 |         1 |       2 |    2 |   -1 |    0 |        1
+   3 |        1 |         1 |       4 |    1 |    1 |    1 |        0
+   4 |        2 |         1 |       4 |    2 |    2 |    1 |        1
+   5 |        3 |         1 |       4 |    3 |    3 |    1 |        2
+   6 |        4 |         1 |       4 |    4 |   -1 |    0 |        3
+   7 |        1 |         2 |       1 |    2 |    1 |    1 |        0
+   8 |        2 |         2 |       1 |    1 |   -1 |    0 |        1
+   9 |        1 |         2 |       4 |    2 |    2 |    1 |        0
+  10 |        2 |         2 |       4 |    3 |    3 |    1 |        1
+  11 |        3 |         2 |       4 |    4 |   -1 |    0 |        2
+(11 rows)
+
+-- q20
 ROLLBACK;
 ROLLBACK