Doc for pgr_dijkstraTRSP

.gitignore

@@ -3,6 +3,8 @@ build
 fix_typos
 code_linter
 
+tools/template/mycreate.sh
+*.sh
 .DS_Store
 .vagrant
 tools/vagrant/packaging.sh

.travis.yml

@@ -1,5 +1,5 @@
 # ------------------------------------------------------------------------------
-# Travis CI scripts 
+# Travis CI scripts
 # Copyright(c) pgRouting Contributors
 #
 # Main configuration
@@ -8,7 +8,7 @@
 #choose trusty
 
 group: edge
-dist: trusty    
+dist: trusty
 sudo: required
 
 
@@ -70,12 +70,11 @@ before_script:
   - ./tools/travis/check-extensions.sh $POSTGRESQL_VERSION ___pgr___test___
 
 
-script: 
+script:
   - ./tools/travis/pgrouting_build.sh $POSTGRESQL_VERSION $POSTGIS_VERSION
   # tests as part of script so if a test fails the build fails
   - ./tools/testers/pg_prove_tests.sh $PG_USER DEBUG
-
-after_script: 
+#after_script:
   - ./tools/travis/pgrouting_test.sh $POSTGRESQL_VERSION $PG_USER -ignorenotice
 
 #after_success:

CMakeLists.txt

@@ -111,7 +111,7 @@ set(PgRouting_SOURCE_NAMES
     "common"
 
     #----------------------
-    # "dijkstra" can not be removed 
+    # "dijkstra" can not be removed
     #   Has the command needed to link with prostgresl
     #----------------------
     "dijkstra" #2.1
@@ -141,9 +141,11 @@ set(PgRouting_SOURCE_NAMES
     "max_flow"    # 2.3
     "contraction" # 2.3
     "pickDeliver" # 2.3
-    "vrp_basic"   # 2.0 
+    "vrp_basic"   # 2.0
     "withPoints"  # 2.2
 
+    "dijkstraTRSP"
+
     # template generated name
     #"funnyDijkstra"
 
@@ -154,7 +156,7 @@ set(PgRouting_SOURCE_NAMES
 #
 #  - <directory>/sql/CMakeLists.txt  must exist
 #-----------------------------------------------------------------------------
-set(PgRouting_SQL_DIRECTORIES 
+set(PgRouting_SQL_DIRECTORIES
 
     "topology"     # needs to be revised
 
@@ -166,7 +168,7 @@ set(PgRouting_SQL_DIRECTORIES
     "costMatrix"   # proposed on 2.3
 
     #----------------------
-    # Wrappers for backwards compatibility 
+    # Wrappers for backwards compatibility
     #----------------------
     "vrppdtw"       # 2.1 wraps of _pgr_pickDeliver
     "deprecated"
@@ -219,7 +221,7 @@ CHECK_CXX_COMPILER_FLAG("-std=c++0x" COMPILER_SUPPORTS_CXX0X)
 CHECK_CXX_COMPILER_FLAG("-std=c++11" COMPILER_SUPPORTS_CXX11)
 if("${CMAKE_CXX_COMPILER_ID}" STREQUAL "GNU")
     if (CMAKE_CXX_COMPILER_VERSION VERSION_LESS GNU_CXX_MINIMUM_VERSION)
-        message(FATAL_ERROR "GCC version must be at least ${GNU_CXX_MINIMUM_VERSION}! 
+        message(FATAL_ERROR "GCC version must be at least ${GNU_CXX_MINIMUM_VERSION}!
         Found version ${CMAKE_CXX_COMPILER_VERSION}")
     endif()
 elseif ("${CMAKE_CXX_COMPILER_ID}" STREQUAL "MSVC")
@@ -360,7 +362,7 @@ endif(NOT PERL_EXECUTABLE)
 #---------------------------------------------
 find_package(PostgreSQL)
 if(NOT POSTGRESQL_FOUND)
-    message(FATAL_ERROR " Please check your PostgreSQL installation.") 
+    message(FATAL_ERROR " Please check your PostgreSQL installation.")
 endif(NOT POSTGRESQL_FOUND)
 
 if(NOT POSTGRESQL_VERSION_STRING)
@@ -372,7 +374,7 @@ string(SUBSTRING "${POSTGRESQL_VERSION_STRING}" 11 -1 POSTGRESQL_VERSION)
 # for XbetaY XalphaY XrcY -> X.Y
 string(REGEX REPLACE "^([0-9]+)[beta|alpha|rc].*" "\\1.0" POSTGRESQL_VERSION ${POSTGRESQL_VERSION})
 
-#for X.Y.Z -> XY  Y<10 
+#for X.Y.Z -> XY  Y<10
 string(REGEX REPLACE "^([0-9]+)\\.([0-9]+).*" "\\1\\2" PGSQL_VERSION ${POSTGRESQL_VERSION})
 
 if("${POSTGRESQL_VERSION}" VERSION_LESS "${POSTGRESQL_MINIMUM_VERSION}")
@@ -402,7 +404,7 @@ find_package(Boost ${BOOST_MINIMUM_VERSION})
 if(Boost_INCLUDE_DIRS)
     message(STATUS "Boost headers were found here: ${Boost_INCLUDE_DIRS}")
 else(Boost_INCLUDE_DIRS)
-    message(FATAL_ERROR " Please check your Boost installation ") 
+    message(FATAL_ERROR " Please check your Boost installation ")
 endif(Boost_INCLUDE_DIRS)
 
 include_directories(${Boost_INCLUDE_DIRS})
@@ -585,7 +587,7 @@ if(WITH_INTERNAL_TESTS)
 endif()
 
 #-------------------
-# add the subdirectories that have the C/C++ code 
+# add the subdirectories that have the C/C++ code
 #-------------------
 
 foreach (subdir ${PgRouting_SOURCE_NAMES})
@@ -683,4 +685,3 @@ if (PGROUTING_DEBUG)
         message(STATUS ${f})
     endforeach()
 endif()
-

ci/appveyor/install.bat

@@ -20,7 +20,7 @@ if not defined COMMON_INSTALL_DIR set COMMON_INSTALL_DIR=%BUILD_ROOT_DIR%\local\
 
 :: for cmake its the min version
 if not defined CMAKE_VERSION set CMAKE_VERSION=3.5.2
-if not defined PG_VERSION set PG_VERSION=2.3.1
+if not defined PG_VERSION set PG_VERSION=2.3.2
 if not defined BOOST_VERSION set BOOST_VERSION=1.58.0
 if not defined CGAL_VERSION set CGAL_VERSION=4.8.1
 

configuration.conf

@@ -28,7 +28,7 @@ contraction         | Y | Y | Y
 pickDeliver         | Y | Y | Y
 vrp_basic           | Y | Y | Y
 withPoints          | Y | Y | Y
-#doc-dijkstraTRSP    | Y | Y | Y
+dijkstraTRSP    | Y | Y | Y
 #areaContraction     | Y | Y | Y
 #connectedComponentsV | Y | Y | Y
 #----------------------

doc/dijkstraTRSP/CMakeLists.txt

@@ -0,0 +1,12 @@
+
+SET(LOCAL_FILES
+    pgr_dijkstraTRSP.rst
+    )
+
+foreach (f ${LOCAL_FILES})
+    configure_file(${f} "${PGR_DOCUMENTATION_SOURCE_DIR}/${f}")
+    list(APPEND LOCAL_DOC_FILES  ${PGR_DOCUMENTATION_SOURCE_DIR}/${f})
+endforeach()
+
+set(PgRouting_DOC_FILES ${PgRouting_DOC_FILES} ${LOCAL_DOC_FILES} PARENT_SCOPE)
+

doc/dijkstraTRSP/pgr_dijkstraTRSP.rst

@@ -0,0 +1,141 @@
+..
+   ****************************************************************************
+    pgRouting Manual
+    Copyright(c) pgRouting Contributors
+
+    This documentation is licensed under a Creative Commons Attribution-Share
+    Alike 3.0 License: http://creativecommons.org/licenses/by-sa/3.0/
+   ****************************************************************************
+
+.. _pgr_dijkstraTRSP:
+
+pgr_dijkstraTRSP
+===============================================================================
+
+``pgr_dijkstraTRSP`` — Returns the shortest path(s) using Dijkstra algorithm.
+In particular, the Dijkstra algorithm implemented by Boost.Graph.
+
+.. figure:: images/boost-inside.jpeg
+   :target: http://www.boost.org/libs/graph/doc/dijkstra_shortest_paths.html
+
+   Boost Graph Inside
+
+
+Synopsis
+-------------------------------------------------------------------------------
+
+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.
+
+Characteristics
+-------------------------------------------------------------------------------
+
+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))`
+
+
+Signature Summary
+-----------------
+
+.. code-block:: none
+
+    pgr_dijkstra(edges_sql, start_vid,  end_vid)
+
+    RETURNS SET OF (seq, path_seq, node, edge, cost, agg_cost)
+        OR EMPTY SET
+
+
+Signatures
+-------------------------------------------------------------------------------
+
+.. index::
+    single: dijkstraTRSP(Minimal Use)
+
+Minimal signature
+.......................................
+
+.. code-block:: none
+
+    pgr_dijkstraTRSP(edges_sql, start_vid, end_vid)
+    RETURNS SET OF (seq, path_seq, node, edge, cost, agg_cost) or EMPTY SET
+
+The minimal signature is for a **directed** graph from one ``start_vid`` to one ``end_vid``:
+
+:Example:
+
+.. literalinclude:: doc-pgr_dijkstraTRSP.queries
+   :start-after: -- q1
+   :end-before: -- q2
+
+
+.. index::
+    single: dijkstraTRSP(Complete signature)
+
+Complete Signature
+.......................................
+
+.. code-block:: none
+
+    pgr_dijkstraTRSP(edges_sql, start_vid, end_vid, directed);
+    RETURNS SET OF (seq, path_seq, node, edge, cost, agg_cost) or EMPTY SET
+
+This signature finds the shortest path from one ``start_vid`` to one ``end_vid``:
+  -  on a **directed** graph when ``directed`` flag is missing or is set to ``true``.
+  -  on an **undirected** graph when ``directed`` flag is set to ``false``.
+
+:Example:
+
+.. literalinclude:: doc-pgr_dijkstraTRSP.queries
+   :start-after: -- q2
+   :end-before: -- q3
+
+
+
+Description of the Signatures
+-------------------------------------------------------------------------------
+
+.. include:: pgRouting-concepts.rst
+    :start-after: basic_edges_sql_start
+    :end-before: basic_edges_sql_end
+
+.. include:: pgr_dijkstra.rst
+    :start-after: pgr_dijkstra_parameters_start
+    :end-before: pgr_dijkstra_parameters_end
+
+.. include:: pgRouting-concepts.rst
+    :start-after: return_path_start
+    :end-before: return_path_end
+
+
+See Also
+-------------------------------------------------------------------------------
+
+* http://en.wikipedia.org/wiki/Dijkstra%27s_algorithm
+* The queries use the :ref:`sampledata` network.
+
+.. rubric:: Indices and tables
+
+* :ref:`genindex`
+* :ref:`search`
+

doc/queries/CMakeLists.txt

@@ -28,6 +28,7 @@ SET(LOCAL_FILES
     doc-contraction.queries
     doc-pgr_bdAstarCost.queries
     doc-pgr_dijkstra.queries
+    doc-pgr_dijkstraTRSP.queries
     doc-pgr_labelGraph.queries
     doc-pgr_withPointsCost.queries
     doc-trsp.queries

doc/queries/doc-pgr_dijkstraTRSP.queries

@@ -0,0 +1,32 @@
+BEGIN;
+BEGIN
+-- q1
+SELECT * FROM pgr_dijkstraTRSP(
+    'SELECT id, source, target, cost, reverse_cost FROM edge_table',
+    2, 3
+);
+ seq | path_seq | node | edge | cost | agg_cost 
+-----+----------+------+------+------+----------
+   1 |        1 |    2 |    4 |    1 |        0
+   2 |        2 |    5 |    8 |    1 |        1
+   3 |        3 |    6 |    9 |    1 |        2
+   4 |        4 |    9 |   16 |    1 |        3
+   5 |        5 |    4 |    3 |    1 |        4
+   6 |        6 |    3 |   -1 |    0 |        5
+(6 rows)
+
+-- q2
+SELECT * FROM pgr_dijkstraTRSP(
+    'SELECT id, source, target, cost, reverse_cost FROM edge_table',
+    2, 3,
+    FALSE
+);
+ seq | path_seq | node | edge | cost | agg_cost 
+-----+----------+------+------+------+----------
+   1 |        1 |    2 |    2 |    1 |        0
+   2 |        2 |    3 |   -1 |    0 |        1
+(2 rows)
+
+-- q3
+ROLLBACK;
+ROLLBACK

doc/src/proposed.rst

@@ -38,19 +38,19 @@ As part of the :ref:`dijkstra`
 .. rubric:: Families
 
 :ref:`astar`
- 
+
 .. include:: aStar-family.rst
    :start-after: index from here
    :end-before: index to here
 
 :ref:`bdAstar`
- 
+
 .. include:: bdAstar-family.rst
    :start-after: index from here
    :end-before: index to here
 
 :ref:`bdDijkstra`
- 
+
 .. include:: bdDijkstra-family.rst
    :start-after: index from here
    :end-before: index to here
@@ -154,6 +154,15 @@ Experimental and Proposed functions
   VRP-category
 
 
+.. rubric:: rewrite of pgr_TRSP
+
+- :ref:`pgr_dijkstraTRSP`
+
+.. toctree::
+  :hidden:
+
+  pgr_dijkstraTRSP
+
 
 ..
   The template
@@ -163,4 +172,3 @@ Experimental and Proposed functions
     :hidden:
     ..
      ../src/funnyDijkstra/doc/pgr_funnyDijkstra.rst
-