From 4eebed768c25713a4cc72bf664a18497df42be63 Mon Sep 17 00:00:00 2001 From: Abhinav Jain Date: Tue, 22 Aug 2023 23:19:16 +0530 Subject: [PATCH] [withPointsKSP][doc] updating user as well as migration documentation and release notes --- NEWS | 22 ++++ doc/conf.py.in | 1 + doc/src/migration.rst | 42 +++++++ doc/src/pgRouting-introduction.rst | 1 + doc/src/release_notes.rst | 22 ++++ doc/withPoints/pgr_withPointsKSP.rst | 178 ++++++++++++++++++++++++--- 6 files changed, 250 insertions(+), 16 deletions(-) diff --git a/NEWS b/NEWS index 3a62d673a50..a0105f5743a 100644 --- 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 index 71e8192c617..be02b21fd01 100644 --- 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 index 4d8e4c6703b..607ba85e9c1 100644 --- 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 `__ + +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 index 4c5dcc5b1db..e2a78809fc2 100644 --- 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 index a24ad3653e0..b073f483eb2 100644 --- 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 `__ 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 `__ To C++ pg data get, diff --git a/doc/withPoints/pgr_withPointsKSP.rst b/doc/withPoints/pgr_withPointsKSP.rst index 1cdb6d51896..d7b640e90eb 100644 --- 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,18 +62,35 @@ 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. @@ -65,6 +98,93 @@ Signatures :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,8 +304,8 @@ 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)`. @@ -167,11 +313,11 @@ 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.