[withPointsKSP][doc] updating user as well as migration documentation…

… and release notes
pgRouting · Aug 22, 2023 · 4eebed7 · 4eebed7
1 parent 06ef775
commit 4eebed7
Show file tree

Hide file tree

Showing 6 changed files with 250 additions and 16 deletions.
diff --git a/NEWS b/NEWS
@@ -41,6 +41,28 @@ pgRouting 3.6.0 Release Notes
     * ``pgr_withPointsDD`` (`Single vertex`) added ``depth`` and ``start_vid`` column.
     * ``pgr_withPointsDD`` (`Multiple vertices`) added ``depth`` column.
 
+* [#2546](https://github.com/pgRouting/pgrouting/pull/2546) Standarize output and modifying signature
+  pgr_withPointsKSP
+
+  * New proposed functions:
+    * ``pgr_withPointsKSP`` (`One to Many`)
+    * ``pgr_withPointsKSP`` (`Many to One`)
+    * ``pgr_withPointsKSP`` (`Many to Many`)
+    * ``pgr_withPointsKSP`` (`Combinations`)
+
+  * New proposed signatures: ``driving side`` parameter changed from optional to compulsory
+
+    * ``pgr_withPointsKSP`` (`One to One`)
+
+  * Deprecated signatures:
+
+    * ``pgr_withpointsksp(text, text, bigint, bigint, integer, boolean, boolean, char, boolean)``
+
+  * Standarizing output columns to |nksp-result|
+
+    * ``pgr_withPointsKSP`` (`One To One`) added ``start_vid`` and ``end_vid`` column.
+
+
 **C/C++ code enhancements**
 
 * [#2504](https://github.com/pgRouting/pgrouting/pull/2504) To C++ pg data get,

diff --git a/doc/conf.py.in b/doc/conf.py.in
@@ -346,6 +346,7 @@ rst_epilog="""
 .. |matrix-pid| replace:: ``(start_pid, end_pid, agg_cost)``
 .. |ksp-result| replace:: ``(seq, path_id, path_seq, node, edge, cost, agg_cost)``
 .. |tsp-result| replace:: ``(seq, node, cost, agg_cost)``
+.. |nksp-result| replace:: ``(seq, path_id, path_seq, start_vid, end_vid, node, edge, cost, agg_cost)``
 .. |old-generic-result| replace:: ``(seq, path_seq, [start_vid], [end_vid], node, edge, cost, agg_cost)``
 .. |old-pid-result| replace:: ``(seq, path_seq, [start_pid], [end_pid], node, edge, cost, agg_cost)``
 .. |pid-1-m| replace:: ``(seq, path_seq, end_pid, node, edge, cost, agg_cost)``

diff --git a/doc/src/migration.rst b/doc/src/migration.rst
@@ -32,6 +32,11 @@ in the new signatures. It works mainly for driving cases, therefore the ``drivin
 parameter changed from optional to compulsory, and its valid values differ for
 directed and undirected graphs.
 
+:doc:`pgr_withPointsKSP` signature have changed, with the addition of new columns
+in the new signature. It works mainly for driving cases, therefore the ``driving side``
+parameter changed from optional to compulsory, and its valid values differ for
+directed and undirected graphs.
+
 .. warning::
    All deprecated functions will be removed on next mayor version 4.0.0
 
@@ -1025,6 +1030,43 @@ values of the function been migrated then:
 * ``id2`` is the node
 * ``id3`` is the edge
 
+Migration of ``pgr_withPointsKSP``
+-------------------------------------------------------------------------------
+
+Starting from `v3.6.0 <https://docs.pgrouting.org/3.6/en/migration.html>`__
+
+Signatures to be migrated:
+
+* ``pgr_withPointsKSP`` (`One to One`)
+
+:Before Migration:
+
+* Output columns were |old-pid-result|
+
+  * Depending on the overload used, the columns ``start_vid`` and ``end_vid``
+    might be missing:
+
+    * ``pgr_withPointsKSP`` (`One to One`) does not have ``start_vid`` and ``end_vid``.
+
+:Migration:
+
+* Be aware of the existance of the additional columns.
+
+* In ``pgr_withPointsKSP`` (`One to One`)
+
+  * ``start_vid`` contains the **start vid** parameter value.
+  * ``end_vid`` contains the **end vid** parameter value.
+
+.. literalinclude:: migration.queries
+   :start-after: --withPointsKSP1
+   :end-before: --withPointsKSP2
+
+* If needed filter out the added columns, for example:
+
+.. literalinclude:: migration.queries
+   :start-after: --withPointsKSP2
+   :end-before: --withPointsKSP3
+
 See Also
 -------------------------------------------------------------------------------
 

diff --git a/doc/src/pgRouting-introduction.rst b/doc/src/pgRouting-introduction.rst
@@ -100,6 +100,7 @@ Individuals (in alphabetical order)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Aasheesh Tiwari,
+Abhinav Jain,
 Aditya Pratap Singh,
 Adrien Berchet,
 Akio Takubo,

diff --git a/doc/src/release_notes.rst b/doc/src/release_notes.rst
@@ -62,6 +62,28 @@ pgRouting 3.6.0 Release Notes
     * ``pgr_withPointsDD`` (`Single vertex`) added ``depth`` and ``start_vid`` column.
     * ``pgr_withPointsDD`` (`Multiple vertices`) added ``depth`` column.
 
+* `#2546 <https://github.com/pgRouting/pgrouting/pull/2546>`__ Standarize output and modifying signature
+  pgr_withPointsKSP
+
+  * New proposed functions:
+    * ``pgr_withPointsKSP`` (`One to Many`)
+    * ``pgr_withPointsKSP`` (`Many to One`)
+    * ``pgr_withPointsKSP`` (`Many to Many`)
+    * ``pgr_withPointsKSP`` (`Combinations`)
+
+  * New proposed signatures: ``driving side`` parameter changed from optional to compulsory
+
+    * ``pgr_withPointsKSP`` (`One to One`)
+
+  * Deprecated signatures:
+
+    * ``pgr_withpointsksp(text, text, bigint, bigint, integer, boolean, boolean, char, boolean)``
+
+  * Standarizing output columns to |nksp-result|
+
+    * ``pgr_withPointsKSP`` (`One To One`) added ``start_vid`` and ``end_vid`` column.
+
+
 .. rubric:: C/C++ code enhancements
 
 * `#2504 <https://github.com/pgRouting/pgrouting/pull/2504>`__ To C++ pg data get,

diff --git a/doc/withPoints/pgr_withPointsKSP.rst b/doc/withPoints/pgr_withPointsKSP.rst
@@ -26,6 +26,22 @@ pgr_withPointsKSP - Proposed
 
 .. rubric:: Availability
 
+* Version 3.6.0
+
+  * New **proposed** function:
+
+    * ``pgr_withPointsKSP`` (`One to Many`_)
+    * ``pgr_withPointsKSP`` (`Many to One`_)
+    * ``pgr_withPointsKSP`` (`Many to Many`_)
+    * ``pgr_withPointsKSP`` (`Combinations`_)
+
+  * Standarizing output columns to |nksp-result|
+
+    * ``pgr_withPointsKSP`` (`One to One`_) added ``start_vid`` and ``end_vid`` columns.
+
+  * Signature change on ``pgr_withPointsKSP`` (`One to One`_)
+
+
 * Version 2.2.0
 
   * New **proposed** function
@@ -46,25 +62,129 @@ Signatures
 .. admonition:: \ \
    :class: signatures
 
-   | pgr_withPointsKSP(`Edges SQL`_, `Points SQL`_ **start vid**, **end vid**, **K**, [**options**])
-   | **options:**  ``[directed, heap_paths, driving_side, details]``
+   | pgr_withPointsKSP(`Edges SQL`_, `Points SQL`_, **start vid**, **end vid**, **K**, **driving_side**, [**options**])
+   | pgr_withPointsKSP(`Edges SQL`_, `Points SQL`_, **start vid**, **end vids**, **K**, **driving_side**, [**options**])
+   | pgr_withPointsKSP(`Edges SQL`_, `Points SQL`_, **start vids**, **end vid**, **K**, **driving_side**, [**options**])
+   | pgr_withPointsKSP(`Edges SQL`_, `Points SQL`_, **start vids**, **end vids**, **K**, **driving_side**, [**options**])
+   | pgr_withPointsKSP(`Edges SQL`_, `Points SQL`_, `Combinations SQL`_, **K**, **driving_side**, [**options**])
+   | **options:**  ``[directed, heap_paths, details]``
 
    | RETURNS SET OF |ksp-result|
    | OR EMPTY SET
 
+.. index::
+    single: withPointsKSP(One to One)
+
+One to One
+...............................................................................
+
+.. admonition:: \ \
+   :class: signatures
+
+   | pgr_withPointsKSP(`Edges SQL`_, `Points SQL`_, **start vid**, **end vid**, **K**, **driving_side**, [**options**])
+   | **options:**  ``[directed, heap_paths, details]``
+
+   | RETURNS SET OF |nksp-result|
+   | OR EMTPY SET
+
 :Example: Get 2 paths from Point :math:`1` to point :math:`2` on a directed
-          graph.
+          graph with **left** side driving.
 
 * For a directed graph.
-* The driving side is set as **b** both. So arriving/departing to/from the
-  point(s) can be in any direction.
 * No details are given about distance of other points of the query.
 * No heap paths are returned.
 
 .. literalinclude:: doc-pgr_withPointsKSP.queries
    :start-after: --q1
    :end-before: --q2
 
+.. index::
+    single: withPointsKSP(One to Many)
+
+One to Many
+...............................................................................
+
+.. admonition:: \ \
+   :class: signatures
+
+   | pgr_withPointsKSP(`Edges SQL`_, `Points SQL`_, **start vid**, **end vids**, **K**, **driving_side**, [**options**])
+   | **options:**  ``[directed, heap_paths, details]``
+
+   | RETURNS SET OF |ksp-result|
+   | OR EMTPY SET
+
+:Example: Get 2 paths from point :math:`1` to point :math:`3` and vertex :math:`7` on an
+          undirected graph
+
+.. literalinclude:: doc-pgr_withPointsKSP.queries
+   :start-after: --q2
+   :end-before: --q3
+
+.. index::
+    single: withPointsKSP(Many to One)
+
+Many to One
+...............................................................................
+
+.. admonition:: \ \
+   :class: signatures
+
+   | pgr_withPointsKSP(`Edges SQL`_, `Points SQL`_, **start vids**, **end vid**, **K**, **driving_side**, [**options**])
+   | **options:**  ``[directed, heap_paths, details]``
+
+   | RETURNS SET OF |ksp-result|
+   | OR EMTPY SET
+
+:Example: Get a path from point :math:`1` and vertex :math:`6` to point :math:`3` on a **directed**
+          graph with **right** side driving and **details** set to **True**
+
+.. literalinclude:: doc-pgr_withPointsKSP.queries
+   :start-after: --q3
+   :end-before: --q4
+
+.. index::
+    single: withPointsKSP(Many to Many)
+
+Many to Many
+...............................................................................
+
+.. admonition:: \ \
+   :class: signatures
+
+   | pgr_withPointsKSP(`Edges SQL`_, `Points SQL`_, **start vids**, **end vids**, **K**, **driving_side**, [**options**])
+   | **options:**  ``[directed, heap_paths, details]``
+
+   | RETURNS SET OF |nksp-result|
+   | OR EMTPY SET
+
+:Example: Get a path from point :math:`1` and vertex :math:`6` to point :math:`3` and vertex :math:`1` on a **directed**
+          graph with **left** side driving and **heap_paths** set to **True**
+
+.. literalinclude:: doc-pgr_withPointsKSP.queries
+   :start-after: --q4
+   :end-before: --q5
+
+.. index::
+    single: withPointsKSP(Combinations)
+
+Combinations
+...............................................................................
+
+.. admonition:: \ \
+   :class: signatures
+
+   | pgr_withPointsKSP(`Edges SQL`_, `Points SQL`_, `Combinations SQL`_, **K**, **driving_side**, [**options**])
+   | **options:**  ``[directed, heap_paths, details]``
+
+   | RETURNS SET OF |ksp-result|
+   | OR EMTPY SET
+
+:Example: Using a combinations table on an **directed** graph
+
+.. literalinclude:: doc-pgr_withPointsKSP.queries
+    :start-after: --q5
+    :end-before: --q6
+
 Parameters
 -------------------------------------------------------------------------------
 
@@ -95,6 +215,13 @@ Parameters
    * - **K**
      - **ANY-INTEGER**
      - Number of required paths
+   * - **driving_side**
+     - **CHAR**
+     - Value in [``r``, ``R``, ``l``, ``L``, ``b``, ``B``] indicating if the driving side is:
+
+       - [``r``, ``R``] for right driving side (for directed graph only)
+       - [``l``, ``L``] for left driving side (for directed graph only)
+       - [``b``, ``B``] for both (only for undirected graph)
 
 Where:
 
@@ -114,12 +241,24 @@ KSP Optional parameters
     :start-after: ksp_optionals_start
     :end-before: ksp_optionals_end
 
-With points optional parameters
+withPointsKSP optional parameters
 ...............................................................................
 
-.. include:: withPoints-family.rst
-    :start-after: withPoints_optionals_start
-    :end-before: withPoints_optionals_end
+.. list-table::
+   :width: 81
+   :widths: 14 7 7 60
+   :header-rows: 1
+
+   * - Parameter
+     - Type
+     - Default
+     - Description
+   * - ``details``
+     - ``BOOLEAN``
+     - ``false``
+     - - When ``true`` the results will include the points that are in the path.
+       - When ``false`` the results will not include the points that are in the
+         path.
 
 Inner Queries
 -------------------------------------------------------------------------------
@@ -138,6 +277,13 @@ Points SQL
     :start-after: points_sql_start
     :end-before: points_sql_end
 
+Combinations SQL
+...............................................................................
+
+.. include:: pgRouting-concepts.rst
+    :start-after: basic_combinations_sql_start
+    :end-before: basic_combinations_sql_end
+
 Result Columns
 -------------------------------------------------------------------------------
 
@@ -158,20 +304,20 @@ Get :math:`2` paths using left side driving topology, from vertex :math:`1` to
 the closest location on the graph of point `(2.9, 1.8)`.
 
 .. literalinclude:: doc-pgr_withPointsKSP.queries
-    :start-after: --q4
-    :end-before: -- q5
+    :start-after: --q6
+    :end-before: --q7
 
 * Point :math:`-1` corresponds to the closest edge from point `(2.9,1.8)`.
 
 Left driving side
 ...............................................................................
 
 Get :math:`2` paths using left side driving topology, from point :math:`1` to
-point :math:`2` with details.
+point :math:`3` with details.
 
 .. literalinclude:: doc-pgr_withPointsKSP.queries
-   :start-after: --q2
-   :end-before: --q3
+   :start-after: --q7
+   :end-before: --q8
 
 Right driving side
 ...............................................................................
@@ -180,8 +326,8 @@ Get :math:`2` paths using right side driving topology from, point :math:`1` to
 point :math:`2` with heap paths and details.
 
 .. literalinclude:: doc-pgr_withPointsKSP.queries
-   :start-after: --q3
-   :end-before: --q4
+   :start-after: --q8
+   :end-before: --q9
 
 The queries use the :doc:`sampledata` network.