Skip to content

Commit

Permalink
Merge branch 'develop' into cuthillMckeeOrdering
Browse files Browse the repository at this point in the history
  • Loading branch information
@cvvergara
cvvergara authored Sep 14, 2022
2 parents afee301 + 806cec7 commit 4a012b4
Show file tree
Hide file tree
Showing 24 changed files with 1,362 additions and 0 deletions.
1 change: 1 addition & 0 deletions configuration.conf
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,7 @@ coloring | Y | Y | Y
planar | Y | Y | Y
dominator | Y | Y | Y
ordering | Y | Y | Y
circuits | Y | Y | Y
#----------------------
# SQL only directories
#----------------------
Expand Down
11 changes: 11 additions & 0 deletions doc/circuits/CMakeLists.txt
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@

SET(LOCAL_FILES
hawickCircuits.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(PROJECT_DOC_FILES ${PROJECT_DOC_FILES} ${LOCAL_DOC_FILES} PARENT_SCOPE)
160 changes: 160 additions & 0 deletions doc/circuits/hawickCircuits.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,160 @@
..
****************************************************************************
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/
****************************************************************************

|
* **Supported versions:**
`Latest <https://docs.pgrouting.org/latest/en/hawickCircuits.html>`__
(`3.4 <https://docs.pgrouting.org/3.4/en/hawickCircuits.html>`__)

``pgr_hawickCircuits - Experimental``
===============================================================================

``pgr_hawickCircuits`` — Returns the list of cirucits using hawickCircuits algorithm.

.. figure:: images/boost-inside.jpeg
:target: https://www.boost.org/libs/graph/doc/dijkstra_shortest_paths.html

.. include:: experimental.rst
:start-after: begin-warn-expr
:end-before: end-warn-expr

.. rubric:: Availability

* Version 3.4.0

* New **experimental** signature:

* ``pgr_hawickCircuits``


Description
-------------------------------------------------------------------------------

Hawick Circuit algorithm, is published in 2008 by Ken Hawick and Health A. James.
This algorithm solves the problem of detecting and enumerating circuits in graphs.
It is capable of circuit enumeration in graphs with directed-arcs, multiple-arcs
and self-arcs with a memory efficient and high-performance im-plementation.
It is an extension of Johnson's Algorithm of finding all the elementary circuits of
a directed graph.

There are 2 variations defined in the Boost Graph Library. Here, we have implemented only
2nd as it serves the most suitable and practical usecase. In this variation we get the
circuits after filtering out the circuits caused by parallel edges. Parallel edge circuits
have more use cases when you want to count the no. of circuits.Maybe in future, we will also
implemenent this variation.

**The main Characteristics are:**

- The algorithm implementation works only for directed graph
- It is a variation of Johnson's algorithm for circuit enumeration.
- The algorithm outputs the distinct circuits present in the graph.
- Time Complexity: :math:`O((V + E) (c + 1))`

- where :math:`|E|` is the number of edges in the graph,
- :math:`|V|` is the number of vertices in the graph.
- :math:`|c|` is the number of circuts in the graph.

Signatures
-------------------------------------------------------------------------------

.. rubric:: Summary

.. parsed-literal::
pgr_hawickCircuits(`Edges SQL`_)
RETURNS SET OF (seq, path_id, path_seq, start_vid, node, edge, cost, agg_cost)
OR EMPTY SET
.. index::
single: Hawick Circuits - Experimental on v3.4

:Example: Circuits present in the pgRouting :doc:`sampledata`

.. literalinclude:: hawickCircuits.queries
:start-after: -- q1
:end-before: -- q2

Parameters
-------------------------------------------------------------------------------

.. include:: allpairs-family.rst
:start-after: edges_start
:end-before: edges_end

Optional parameters
...............................................................................

.. include:: dijkstra-family.rst
:start-after: dijkstra_optionals_start
:end-before: dijkstra_optionals_end

Inner Queries
-------------------------------------------------------------------------------

Edges SQL
...............................................................................

.. include:: pgRouting-concepts.rst
:start-after: no_id_edges_sql_start
:end-before: no_id_edges_sql_end

Return columns
-------------------------------------------------------------------------------

.. list-table::
:width: 81
:widths: auto
:header-rows: 1

* - Column
- Type
- Description
* - ``seq``
- ``INTEGER``
- Sequential value starting from ``1``
* - ``path_id``
- ``INTEGER``
- Id of the circuit starting from ``1``
* - ``path_seq``
- ``INTEGER``
- Relative postion in the path. Has value ``0`` for beginning of the path
* - ``start_vid``
- ``BIGINT``
- Identifier of the starting vertex of the circuit.
* - ``end_vid``
- ``BIGINT``
- Identifier of the ending vertex of the circuit.
* - ``node``
- ``BIGINT``
- Identifier of the node in the path from a vid to next vid.
* - ``edge``
- ``BIGINT``
- Identifier of the edge used to go from ``node`` to the next node in
the path sequence. ``-1`` for the last node of the path.
* - ``cost``
- ``FLOAT``
- Cost to traverse from ``node`` using ``edge`` to the next node in the
path sequence.
* - ``agg_cost``
- ``FLOAT``
- Aggregate cost from ``start_v`` to ``node``.


See Also
-------------------------------------------------------------------------------

* :doc:`sampledata`
* `Boost: Hawick Circuit Algorithm
<https://www.boost.org/doc/libs/1_78_0/libs/graph/doc/hawick_circuits.html>`__

.. rubric:: Indices and tables

* :ref:`genindex`
* :ref:`search`
1 change: 1 addition & 0 deletions doc/conf.py.in
View file
Original file line number Diff line number Diff line change
Expand Up @@ -332,6 +332,7 @@ linkcheck_ignore = [
r'https://docs.pgrouting.org/.*/.*/pgr_degree.html',
r'https://docs.pgrouting.org/.*/.*/cuthillMckeeOrdering.html',
r'https://docs.pgrouting.org/.*/.*/ordering-family.html',
r'https://docs.pgrouting.org/.*/.*/hawickCircuits.html',
r'https://docs.pgrouting.org/.*/.*/pgr_findCloseEdges.html',

# link failing used in contraction-family
Expand Down
2 changes: 2 additions & 0 deletions doc/src/experimental.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -132,6 +132,7 @@ Experimental Functions
- :doc:`pgr_topologicalSort`
- :doc:`pgr_transitiveClosure`
- :doc:`pgr_lengauerTarjanDominatorTree`
- :doc:`hawickCircuits`

.. toctree::
:hidden:
Expand All @@ -146,6 +147,7 @@ Experimental Functions
pgr_topologicalSort
pgr_transitiveClosure
pgr_lengauerTarjanDominatorTree
hawickCircuits


See Also
Expand Down
2 changes: 2 additions & 0 deletions doc/src/pgRouting-introduction.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,7 @@ Individuals in this release (in alphabetical order)
Ashish Kumar,
Cayetano Benavent,
Daniel Kastl,
Nitish Chauhan,
Rajat Shinde,
Regina Obe,
Shobhit Chaurasia,
Expand Down Expand Up @@ -150,6 +151,7 @@ Maoguang Wang,
Mohamed Bakli,
Mohamed Zia,
Mukul Priya,
Nitish Chauhan,
Rajat Shinde,
Razequl Islam,
Regina Obe,
Expand Down
11 changes: 11 additions & 0 deletions docqueries/circuits/CMakeLists.txt
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# Do not use extensions
SET(LOCAL_FILES
hawickCircuits
)

foreach (f ${LOCAL_FILES})
configure_file("${f}.result" "${PGR_DOCUMENTATION_SOURCE_DIR}/${f}.queries")
list(APPEND LOCAL_DOC_FILES "${PGR_DOCUMENTATION_SOURCE_DIR}/${f}.queries")
endforeach()

set(PROJECT_DOC_FILES ${PROJECT_DOC_FILES} ${LOCAL_DOC_FILES} PARENT_SCOPE)
109 changes: 109 additions & 0 deletions docqueries/circuits/hawickCircuits.result
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,109 @@
BEGIN;
BEGIN
SET client_min_messages TO NOTICE;
SET
/* -- q1 */
SELECT * FROM pgr_hawickCircuits(
'SELECT id, source, target, cost, reverse_cost FROM edges'
);
seq | path_id | path_seq | start_vid | end_vid | node | edge | cost | agg_cost
-----+---------+----------+-----------+---------+------+------+------+----------
1 | 1 | 0 | 1 | 1 | 1 | 6 | 1 | 0
2 | 1 | 1 | 1 | 1 | 3 | 6 | 1 | 1
3 | 1 | 2 | 1 | 1 | 1 | -1 | 0 | 2
4 | 2 | 0 | 3 | 3 | 3 | 7 | 1 | 0
5 | 2 | 1 | 3 | 3 | 7 | 7 | 1 | 1
6 | 2 | 2 | 3 | 3 | 3 | -1 | 0 | 2
7 | 3 | 0 | 7 | 7 | 7 | 4 | 1 | 0
8 | 3 | 1 | 7 | 7 | 6 | 4 | 1 | 1
9 | 3 | 2 | 7 | 7 | 7 | -1 | 0 | 2
10 | 4 | 0 | 7 | 7 | 7 | 8 | 1 | 0
11 | 4 | 1 | 7 | 7 | 11 | 8 | 1 | 1
12 | 4 | 2 | 7 | 7 | 7 | -1 | 0 | 2
13 | 5 | 0 | 7 | 7 | 7 | 8 | 1 | 0
14 | 5 | 1 | 7 | 7 | 11 | 11 | 1 | 1
15 | 5 | 2 | 7 | 7 | 12 | 13 | 1 | 2
16 | 5 | 3 | 7 | 7 | 17 | 15 | 1 | 3
17 | 5 | 4 | 7 | 7 | 16 | 16 | 1 | 4
18 | 5 | 5 | 7 | 7 | 15 | 3 | 1 | 5
19 | 5 | 6 | 7 | 7 | 10 | 2 | 1 | 6
20 | 5 | 7 | 7 | 7 | 6 | 4 | 1 | 7
21 | 5 | 8 | 7 | 7 | 7 | -1 | 0 | 8
22 | 6 | 0 | 7 | 7 | 7 | 8 | 1 | 0
23 | 6 | 1 | 7 | 7 | 11 | 9 | 1 | 1
24 | 6 | 2 | 7 | 7 | 16 | 16 | 1 | 2
25 | 6 | 3 | 7 | 7 | 15 | 3 | 1 | 3
26 | 6 | 4 | 7 | 7 | 10 | 2 | 1 | 4
27 | 6 | 5 | 7 | 7 | 6 | 4 | 1 | 5
28 | 6 | 6 | 7 | 7 | 7 | -1 | 0 | 6
29 | 7 | 0 | 7 | 7 | 7 | 10 | 1 | 0
30 | 7 | 1 | 7 | 7 | 8 | 10 | 1 | 1
31 | 7 | 2 | 7 | 7 | 7 | -1 | 0 | 2
32 | 8 | 0 | 7 | 7 | 7 | 10 | 1 | 0
33 | 8 | 1 | 7 | 7 | 8 | 12 | 1 | 1
34 | 8 | 2 | 7 | 7 | 12 | 13 | 1 | 2
35 | 8 | 3 | 7 | 7 | 17 | 15 | 1 | 3
36 | 8 | 4 | 7 | 7 | 16 | 9 | 1 | 4
37 | 8 | 5 | 7 | 7 | 11 | 8 | 1 | 5
38 | 8 | 6 | 7 | 7 | 7 | -1 | 0 | 6
39 | 9 | 0 | 7 | 7 | 7 | 10 | 1 | 0
40 | 9 | 1 | 7 | 7 | 8 | 12 | 1 | 1
41 | 9 | 2 | 7 | 7 | 12 | 13 | 1 | 2
42 | 9 | 3 | 7 | 7 | 17 | 15 | 1 | 3
43 | 9 | 4 | 7 | 7 | 16 | 16 | 1 | 4
44 | 9 | 5 | 7 | 7 | 15 | 3 | 1 | 5
45 | 9 | 6 | 7 | 7 | 10 | 2 | 1 | 6
46 | 9 | 7 | 7 | 7 | 6 | 4 | 1 | 7
47 | 9 | 8 | 7 | 7 | 7 | -1 | 0 | 8
48 | 10 | 0 | 7 | 7 | 7 | 10 | 1 | 0
49 | 10 | 1 | 7 | 7 | 8 | 12 | 1 | 1
50 | 10 | 2 | 7 | 7 | 12 | 13 | 1 | 2
51 | 10 | 3 | 7 | 7 | 17 | 15 | 1 | 3
52 | 10 | 4 | 7 | 7 | 16 | 16 | 1 | 4
53 | 10 | 5 | 7 | 7 | 15 | 3 | 1 | 5
54 | 10 | 6 | 7 | 7 | 10 | 5 | 1 | 6
55 | 10 | 7 | 7 | 7 | 11 | 8 | 1 | 7
56 | 10 | 8 | 7 | 7 | 7 | -1 | 0 | 8
57 | 11 | 0 | 6 | 6 | 6 | 1 | 1 | 0
58 | 11 | 1 | 6 | 6 | 5 | 1 | 1 | 1
59 | 11 | 2 | 6 | 6 | 6 | -1 | 0 | 2
60 | 12 | 0 | 10 | 10 | 10 | 5 | 1 | 0
61 | 12 | 1 | 10 | 10 | 11 | 11 | 1 | 1
62 | 12 | 2 | 10 | 10 | 12 | 13 | 1 | 2
63 | 12 | 3 | 10 | 10 | 17 | 15 | 1 | 3
64 | 12 | 4 | 10 | 10 | 16 | 16 | 1 | 4
65 | 12 | 5 | 10 | 10 | 15 | 3 | 1 | 5
66 | 12 | 6 | 10 | 10 | 10 | -1 | 0 | 6
67 | 13 | 0 | 10 | 10 | 10 | 5 | 1 | 0
68 | 13 | 1 | 10 | 10 | 11 | 9 | 1 | 1
69 | 13 | 2 | 10 | 10 | 16 | 16 | 1 | 2
70 | 13 | 3 | 10 | 10 | 15 | 3 | 1 | 3
71 | 13 | 4 | 10 | 10 | 10 | -1 | 0 | 4
72 | 14 | 0 | 11 | 11 | 11 | 11 | 1 | 0
73 | 14 | 1 | 11 | 11 | 12 | 13 | 1 | 1
74 | 14 | 2 | 11 | 11 | 17 | 15 | 1 | 2
75 | 14 | 3 | 11 | 11 | 16 | 9 | 1 | 3
76 | 14 | 4 | 11 | 11 | 11 | -1 | 0 | 4
77 | 15 | 0 | 11 | 11 | 11 | 9 | 1 | 0
78 | 15 | 1 | 11 | 11 | 16 | 9 | 1 | 1
79 | 15 | 2 | 11 | 11 | 11 | -1 | 0 | 2
80 | 16 | 0 | 8 | 8 | 8 | 14 | 1 | 0
81 | 16 | 1 | 8 | 8 | 9 | 14 | 1 | 1
82 | 16 | 2 | 8 | 8 | 8 | -1 | 0 | 2
83 | 17 | 0 | 2 | 2 | 2 | 17 | 1 | 0
84 | 17 | 1 | 2 | 2 | 4 | 17 | 1 | 1
85 | 17 | 2 | 2 | 2 | 2 | -1 | 0 | 2
86 | 18 | 0 | 13 | 13 | 13 | 18 | 1 | 0
87 | 18 | 1 | 13 | 13 | 14 | 18 | 1 | 1
88 | 18 | 2 | 13 | 13 | 13 | -1 | 0 | 2
89 | 19 | 0 | 17 | 17 | 17 | 15 | 1 | 0
90 | 19 | 1 | 17 | 17 | 16 | 15 | 1 | 1
91 | 19 | 2 | 17 | 17 | 17 | -1 | 0 | 2
92 | 20 | 0 | 16 | 16 | 16 | 16 | 1 | 0
93 | 20 | 1 | 16 | 16 | 15 | 16 | 1 | 1
94 | 20 | 2 | 16 | 16 | 16 | -1 | 0 | 2
(94 rows)

/* -- q2 */
ROLLBACK;
ROLLBACK
5 changes: 5 additions & 0 deletions docqueries/circuits/hawickCircuits.test.sql
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
/* -- q1 */
SELECT * FROM pgr_hawickCircuits(
'SELECT id, source, target, cost, reverse_cost FROM edges'
);
/* -- q2 */
16 changes: 16 additions & 0 deletions docqueries/circuits/test.conf
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
#!/usr/bin/perl -w

%main::tests = (
'any' => {
'comment' => 'pgr_hawickCircuits algorithm tests',
'data' => ["" ],
'tests' => [qw(
hawickCircuits
)],
'documentation' => [qw(
hawickCircuits
)]
},
);

1;
Loading

0 comments on commit 4a012b4

Please sign in to comment.