Dijkstra parsed literal (#2262)

* [dijkstraCost][doc] using parsed-literal & refining * [dijkstraCostMatrix][doc] using parsed-literal & refining * [dijkstraVia][doc] using parsed-literal & refining * [dijkstraNear][doc] using parsed-literal & refining
pgRouting · Mar 31, 2022 · 88b4f07 · 88b4f07
1 parent d2a98bf
commit 88b4f07
Show file tree

Hide file tree

Showing 20 changed files with 515 additions and 505 deletions.
diff --git a/doc/dijkstra/dijkstra-family.rst b/doc/dijkstra/dijkstra-family.rst
@@ -81,6 +81,9 @@ This implementation can be used with a directed graph and an undirected graph.
 The main characteristics are:
 
 - Process is done only on edges with positive costs.
+
+  - A negative value on a cost column is interpreted as the edge does not exist.
+
 - Values are returned when there is a path.
 - When there is no path:
 
@@ -152,7 +155,7 @@ Optional parameters
    * - ``directed``
      - ``BOOLEAN``
      - ``true``
-     - * When ``true`` Graph is considered `Directed`
+     - * When ``true`` the graph is considered `Directed`
        * When ``false`` the graph is considered as `Undirected`.
 
 .. dijkstra_optionals_end

diff --git a/doc/dijkstra/pgr_dijkstra.rst b/doc/dijkstra/pgr_dijkstra.rst
@@ -27,8 +27,7 @@
 ``pgr_dijkstra``
 ===============================================================================
 
-``pgr_dijkstra`` — Returns the shortest path(s) using Dijkstra algorithm.
-In particular, the Dijkstra algorithm implemented by Boost.Graph.
+``pgr_dijkstra`` — Shortest path(s) using Dijkstra algorithm.
 
 .. figure:: images/boost-inside.jpeg
    :target: https://www.boost.org/libs/graph/doc/dijkstra_shortest_paths.html
@@ -75,33 +74,7 @@ Description
     :start-after: dijkstra_details_start
     :end-before: dijkstra_details_end
 
-Dijkstra's algorithm, conceived by Dutch computer scientist Edsger Dijkstra in
-1956.
-It is a graph search algorithm that solves the shortest path problem for a graph
-with non-negative edge path costs, producing a shortest path from a starting
-vertex (**start vid**) to an ending vertex (**end vid**).
-This implementation can be used with a directed graph and an undirected graph.
-
-The main characteristics are:
-  - Process is done only on edges with positive costs.
-  - Values are returned when there is a path.
-
-    - When the starting vertex and ending vertex are the same, there is no path.
-
-      - The `agg_cost` the non included values `(v, v)` is `0`
-
-    - When the starting vertex and ending vertex are the different and there is no path:
-
-      - The `agg_cost` the non included values `(u, v)` is :math:`\infty`
-
-  - For optimization purposes, any duplicated value in the `start vids` or `end vids` are ignored.
-
-  - The returned values are ordered:
-
-    - ``start_vid`` ascending
-    - ``end vid`` ascending
-
-  - Running time: :math:`O(| start\_vids | * (V \log V + E))`
+- Running time: :math:`O(| start\_vids | * (V \log V + E))`
 
 Signatures
 -------------------------------------------------------------------------------

diff --git a/doc/dijkstra/pgr_dijkstraCost.rst b/doc/dijkstra/pgr_dijkstraCost.rst
@@ -23,10 +23,7 @@
 pgr_dijkstraCost
 ===============================================================================
 
-``pgr_dijkstraCost``
-
-Using Dijkstra algorithm implemented by Boost.Graph, and extract only the
-aggregate cost of the shortest path(s) found, for the combination of vertices given.
+``pgr_dijkstraCost`` - Total cost of the shortest path(s) using Dijkstra algorithm.
 
 .. figure:: images/boost-inside.jpeg
    :target: https://www.boost.org/libs/graph/doc/dijkstra_shortest_paths.html
@@ -39,7 +36,7 @@ aggregate cost of the shortest path(s) found, for the combination of vertices gi
 
   * New **Proposed** functions:
 
-    * pgr_dijkstraCost(combinations)
+    * ``pgr_dijkstra`` (`Combinations`_)
 
 * Version 2.2.0
 
@@ -49,81 +46,57 @@ aggregate cost of the shortest path(s) found, for the combination of vertices gi
 Description
 -------------------------------------------------------------------------------
 
-The ``pgr_dijkstraCost`` algorithm, is a good choice to calculate the sum of the costs
-of the shortest path for a subset of pairs of nodes of the graph.
-We make use of the Boost's implementation of dijkstra which runs in
-:math:`O(V \log V + E)` time.
-
-The main characteristics are:
-  - It does not return a path.
-  - Returns the sum of the costs of the shortest path for pair combination of nodes in the graph.
-  - Process is done only on edges with positive costs.
-  - Values are returned when there is a path.
-
-    - The returned values are in the form of a set of `(start_vid, end_vid, agg_cost)`.
-
-    - When the starting vertex and ending vertex are the same, there is no path.
-
-      - The `agg_cost` int the non included values `(v, v)` is `0`
-
-    - When the starting vertex and ending vertex are the different and there is no path.
+The ``pgr_dijkstraCost`` function sumarizes of the cost of the shortest path(s).
 
-      - The `agg_cost` in the non included values `(u, v)` is :math:`\infty`
+.. include:: dijkstra-family.rst
+    :start-after: dijkstra_description_start
+    :end-before: dijkstra_description_end
 
-  - Let be the case the values returned are stored in a table, so the unique index would be the pair:
-    `(start_vid, end_vid)`.
+.. include:: dijkstra-family.rst
+    :start-after: dijkstra_details_start
+    :end-before: dijkstra_details_end
 
-  - For undirected graphs, the results are symmetric.
+- It does not return a path.
+- Returns the sum of the costs of the shortest path of each pair combination of
+  nodes requested.
+- Let be the case the values returned are stored in a table, so the unique index
+  would be the pair: `(start_vid, end_vid)`
 
-    - The  `agg_cost` of `(u, v)` is the same as for `(v, u)`.
+- For undirected graphs, the results are symmetric.
 
-  - Any duplicated value in the `start_vids` or `end_vids` is ignored.
+  - The  `agg_cost` of `(u, v)` is the same as for `(v, u)`.
 
-  - The returned values are ordered:
+- The returned values are ordered in ascending order:
 
-    - `start_vid` ascending
-    - `end_vid` ascending
+  - `start_vid` ascending
+  - `end_vid` ascending
 
-  - Running time: :math:`O(| start\_vids | * (V \log V + E))`
+- Running time: :math:`O(| start\_vids | * (V \log V + E))`
 
 Signatures
 -------------------------------------------------------------------------------
 
 .. rubric:: Summary
 
-.. code-block:: none
-
-     pgr_dijkstraCost(edges_sql, from_vid,  to_vid  [, directed])
-     pgr_dijkstraCost(edges_sql, from_vid,  to_vids [, directed])
-     pgr_dijkstraCost(edges_sql, from_vids, to_vid  [, directed])
-     pgr_dijkstraCost(edges_sql, from_vids, to_vids [, directed])
-     pgr_dijkstraCost(edges_sql, combinations_sql   [, directed])
-     RETURNS SET OF (start_vid, end_vid, agg_cost)
-     OR EMPTY SET
-
-.. rubric:: Using defaults
-
-.. code-block:: none
-
-     pgr_dijkstraCost(edges_sql, from_vid,  to_vid)
-     RETURNS SET OF (start_vid, end_vid, agg_cost)
-     OR EMPTY SET
+.. parsed-literal::
 
-:Example: From vertex :math:`2` to vertex  :math:`3` on a **directed** graph
-
-.. literalinclude:: doc-pgr_dijkstraCost.queries
-   :start-after: -- q1
-   :end-before: -- q2
+  pgr_dijkstraCost(`Edges SQL`_, **start vid**, **end vid**  [, directed])
+  pgr_dijkstraCost(`Edges SQL`_, **start vid**, **end vids** [, directed])
+  pgr_dijkstraCost(`Edges SQL`_, **start vids**, **end vid**  [, directed])
+  pgr_dijkstraCost(`Edges SQL`_, **start vids**, **end vids** [, directed])
+  pgr_dijkstraCost(`Edges SQL`_, `Combinations SQL`_ [, directed])
+  RETURNS SET OF (start_vid, end_vid, agg_cost)
+  OR EMPTY SET
 
 .. index::
 	single: dijkstraCost(One to One)
 
 One to One
 ...............................................................................
 
-.. code-block:: none
+.. parsed-literal::
 
-    pgr_dijkstraCost(edges_sql, from_vid,  to_vid  [, directed])
+    pgr_dijkstraCost(`Edges SQL`_, **start vid**, **end vid**  [, directed])
     RETURNS SET OF (start_vid, end_vid, agg_cost)
     OR EMPTY SET
 
@@ -139,13 +112,14 @@ One to One
 One to Many
 ...............................................................................
 
-.. code-block:: none
+.. parsed-literal::
 
-    pgr_dijkstraCost(edges_sql, from_vid,  to_vids [, directed])
+    pgr_dijkstraCost(`Edges SQL`_, **start vid**, **end vids** [, directed])
     RETURNS SET OF (start_vid, end_vid, agg_cost)
     OR EMPTY SET
 
-:Example: From vertex :math:`2` to vertices :math:`\{3, 11\}` on a **directed** graph
+:Example: From vertex :math:`2` to vertices :math:`\{3, 11\}` on a **directed**
+          graph
 
 .. literalinclude:: doc-pgr_dijkstraCost.queries
    :start-after: -- q4
@@ -157,13 +131,14 @@ One to Many
 Many to One
 ...............................................................................
 
-.. code-block:: none
+.. parsed-literal::
 
-    pgr_dijkstraCost(edges_sql, from_vids, to_vid  [, directed])
+    pgr_dijkstraCost(`Edges SQL`_, **start vids**, **end vid**  [, directed])
     RETURNS SET OF (start_vid, end_vid, agg_cost)
     OR EMPTY SET
 
-:Example: From vertices :math:`\{2, 7\}` to vertex :math:`3` on a **directed** graph
+:Example: From vertices :math:`\{2, 7\}` to vertex :math:`3` on a **directed**
+          graph
 
 .. literalinclude:: doc-pgr_dijkstraCost.queries
     :start-after: -- q3
@@ -175,37 +150,44 @@ Many to One
 Many to Many
 ...............................................................................
 
-.. code-block:: none
+.. parsed-literal::
 
-    pgr_dijkstraCost(edges_sql, from_vids, to_vids [, directed])
+    pgr_dijkstraCost(`Edges SQL`_, **start vids**, **end vids** [, directed])
     RETURNS SET OF (start_vid, end_vid, agg_cost)
     OR EMPTY SET
 
-:Example: From vertices :math:`\{2, 7\}` to vertices :math:`\{3, 11\}` on a **directed** graph
+:Example: From vertices :math:`\{2, 7\}` to vertices :math:`\{3, 11\}` on a
+          **directed** graph
 
 .. literalinclude:: doc-pgr_dijkstraCost.queries
    :start-after: -- q5
-   :end-before: -- q6
+   :end-before: -- q51
 
 .. index::
     single: dijkstraCost(Combinations) - Proposed on v3.1
 
 Combinations
 ...............................................................................
 
-.. code-block:: none
+.. parsed-literal::
 
-    pgr_dijkstraCost(TEXT edges_sql, TEXT combination_sql, BOOLEAN directed:=true);
+    pgr_dijkstraCost(`Edges SQL`_, `Combinations SQL`_ [, directed])
     RETURNS SET OF (start_vid, end_vid, agg_cost)
     OR EMPTY SET
 
 :Example: Using a combinations table on an **undirected** graph
 
+The table contents:
+
 .. literalinclude:: doc-pgr_dijkstraCost.queries
-   :start-after: -- q8
-   :end-before: -- q9
+   :start-after: -- q51
+   :end-before: -- q52
 
+The query:
 
+.. literalinclude:: doc-pgr_dijkstraCost.queries
+   :start-after: -- q52
+   :end-before: -- q6
 
 Parameters
 -------------------------------------------------------------------------------
@@ -245,7 +227,6 @@ Return Columns
     :start-after: return_cost_start
     :end-before: return_cost_end
 
-
 Additional Examples
 -------------------------------------------------------------------------------
 
@@ -255,17 +236,17 @@ Additional Examples
     :start-after: -- q6
     :end-before: -- q7
 
-:Example 2: Making `start_vids` the same as `end_vids`
+:Example 2: Making ``start_vids`` the same as ``end_vids``.
 
 .. literalinclude:: doc-pgr_dijkstraCost.queries
     :start-after: -- q7
     :end-before: -- q8
 
-:Example 3: Four manually assigned (source, target) vertex combinations
+:Example 3: Manually assigned vertex combinations.
 
 .. literalinclude:: doc-pgr_dijkstraCost.queries
-   :start-after: -- q9
-   :end-before: -- q10
+   :start-after: -- q8
+   :end-before: -- q9
 
 See Also
 -------------------------------------------------------------------------------
@@ -277,4 +258,3 @@ See Also
 
 * :ref:`genindex`
 * :ref:`search`
-