From d3265423ae0d45c3d53d12c85e01d58f9be1f359 Mon Sep 17 00:00:00 2001 From: Abhinav Jain Date: Mon, 21 Aug 2023 03:11:46 +0530 Subject: [PATCH] [withPointsKSP][doc] updating user as well as migration documentation --- doc/conf.py.in | 1 + doc/src/migration.rst | 42 +++++++ doc/src/pgRouting-introduction.rst | 1 + doc/withPoints/pgr_withPointsKSP.rst | 180 ++++++++++++++++++++++++--- 4 files changed, 207 insertions(+), 17 deletions(-) diff --git a/doc/conf.py.in b/doc/conf.py.in index 71e8192c61..be02b21fd0 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 4d8e4c6703..607ba85e9c 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 4c5dcc5b1d..e2a78809fc 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/withPoints/pgr_withPointsKSP.rst b/doc/withPoints/pgr_withPointsKSP.rst index 1cdb6d5189..edb6b967a9 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,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 +.. literalinclude:: doc-pgr_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,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.