Skip to content

New signature pgr contraction #2789

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 11 commits into from
Mar 22, 2025
Merged

New signature pgr contraction #2789

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
620c054
(contraction/pgtap) the tests that need to pass
cvvergara Mar 20, 2025
6fbf5f5
(contraction/docqueries) Ajusting the documentation queries
cvvergara Mar 20, 2025
0e0e222
(contraction/sql) The new signature and deprecation of the other
cvvergara Mar 20, 2025
fe9b0ec
(contraction/doc) Updating and refinement of the documentation
cvvergara Mar 20, 2025
81fc9ed
(lint) removing files no longer in use
cvvergara Mar 20, 2025
7ea07eb
(doc) documenting changes on release notes & NEWS
cvvergara Mar 20, 2025
e8c8bcd
Update locale: commit 7ea07eb9a
github-actions[bot] Mar 21, 2025
4110936
(contraction/pgtap) moving functions to function file
cvvergara Mar 21, 2025
435c54a
(contraction/sql) fixing parameter mismatch on notice
cvvergara Mar 21, 2025
cf2d5af
(contraction/doc) improving readability
cvvergara Mar 21, 2025
3068330
Update locale: commit cf2d5af00
github-actions[bot] Mar 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions NEWS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,17 @@
* ``partial`` option is removed.
* Function promoted to official.

**Official functions changes**

* [#2786](https://github.com/pgRouting/pgrouting/issues/2786): pgr_contraction

* New signature:
* Previously compulsory parameter **Contraction order** is now optional with
name ``methods``.
* New name and order of optional parameters.
* Deprecated signature pgr_contraction(text,bigint[],integer,bigint[],boolean)


## pgRouting 3.7

### pgRouting 3.7.3 Release Notes
Expand Down
322 changes: 1 addition & 321 deletions doc/contraction/contraction-family.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -293,7 +293,7 @@ Linear vertex on directed graph

- The green nodes are `linear`_ nodes
- The blue nodes have an unlimited number of incoming and outgoing edges.
- The white node is not linear because the linearity is not symetrical.
- The white node is not linear because the linearity is not symmetrical.

* It is possible to go :math:`y \rightarrow c \rightarrow z`
* It's not possible to go :math:`z \rightarrow c \rightarrow y`
Expand Down Expand Up @@ -400,326 +400,6 @@ Contracting :math:`v`:
Edge :math:`u \rightarrow z` has the information of nodes that were contracted.


The cycle
-------------------------------------------------------------------------------

Contracting a graph, can be done with more than one operation.
The order of the operations affect the resulting contracted graph, after
applying one operation, the set of vertices that can be contracted
by another operation changes.

This implementation, cycles ``max_cycles`` times through ``operations_order`` .

.. parsed-literal::

<input>
do max_cycles times {
for (operation in operations_order)
{ do operation }
}
<output>


Contracting sample data
-------------------------------------------------------------------------------

In this section, building and using a contracted graph will be shown by example.

- The :doc:`sampledata` for an undirected graph is used
- a dead end operation first followed by a linear operation.


.. contents::
:local:

Construction of the graph in the database
...............................................................................

.. rubric:: Original Data

The following query shows the original data involved in the contraction
operation.

.. literalinclude:: contraction-family.queries
:start-after: -- q00
:end-before: -- q01

The original graph:

.. image:: /images/Fig6-undirected.png
:scale: 25%

Contraction results
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

The results do not represent the contracted graph.
They represent the changes done to the graph after applying the contraction
algorithm.

Observe that vertices, for example, :math:`6` do not appear in the results
because it was not affected by the contraction algorithm.

.. literalinclude:: contraction-family.queries
:start-after: -- q2
:end-before: -- q3

After doing the dead end contraction operation:

.. image:: images/undirected_sampledata_b.png
:scale: 25%

After doing the linear contraction operation to the graph above:

.. image:: images/undirected_sampledata_c.png
:scale: 25%

The process to create the contraction graph on the database:

.. contents::
:local:

Add additional columns
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Adding extra columns to the ``edge_table`` and ``edge_table_vertices_pgr``
tables, where:

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

* - Column
- Description
* - ``contracted_vertices``
- The vertices set belonging to the vertex/edge
* - ``is_contracted``
- On the vertex table

* when ``true`` the vertex is contracted, its not part of the contracted
graph.
* when ``false`` the vertex is not contracted, its part of the contracted
graph.
* - ``is_new``
- On the edge table

* when ``true`` the edge was generated by the contraction algorithm. its
part of the contracted graph.
* when ``false`` the edge is an original edge, might be or not part of
the contracted graph.

.. literalinclude:: contraction-family.queries
:start-after: -- q1
:end-before: -- q2

Store contraction information
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Store the `contraction results`_ in a table

.. literalinclude:: contraction-family.queries
:start-after: -- q3
:end-before: -- q4


The vertex table update
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Use ``is_contracted`` column to indicate the vertices that are contracted.

.. literalinclude:: contraction-family.queries
:start-after: -- q4
:end-before: -- q5

Fill ``contracted_vertices`` with the information from the results tha belong to
the vertices.

.. literalinclude:: contraction-family.queries
:start-after: -- q6
:end-before: -- q7

The modified vertices table:

.. literalinclude:: contraction-family.queries
:start-after: -- q7
:end-before: -- q8

The edge table update
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Insert the new edges generated by pgr_contraction.

.. literalinclude:: contraction-family.queries
:start-after: -- q8
:end-before: -- q9

The modified ``edge_table``.

.. literalinclude:: contraction-family.queries
:start-after: -- q9
:end-before: -- q10


The contracted graph
...............................................................................

Vertices that belong to the contracted graph.
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

.. literalinclude:: contraction-family.queries
:start-after: -- q10
:end-before: -- q11

Edges that belong to the contracted graph.
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

.. literalinclude:: contraction-family.queries
:start-after: -- q11
:end-before: -- case1

Contracted graph
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

.. image:: images/newgraph.png
:scale: 25%

Using the contracted graph
...............................................................................

Using the contracted graph with ``pgr_dijkstra``

There are three cases when calculating the shortest path between a given source
and target in a contracted graph:

- Case 1: Both source and target belong to the contracted graph.
- Case 2: Source and/or target belong to an edge subgraph.
- Case 3: Source and/or target belong to a vertex.

Case 1: Both source and target belong to the contracted graph.
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Using the `Edges that belong to the contracted graph.`_ on lines 11 to 20.

.. literalinclude:: contraction-family.queries
:emphasize-lines: 11-20
:start-after: -- case1
:end-before: -- use1
:linenos:

.. rubric:: Case 1

When both source and target belong to the contracted graph, a path is found.

.. literalinclude:: contraction-family.queries
:start-after: -- use1
:end-before: -- use1-1

.. rubric:: Case 2

When source and/or target belong to an edge subgraph then a path is not found.

In this case, the contracted graph do not have an edge connecting with
node :math:`4`.

.. literalinclude:: contraction-family.queries
:start-after: -- use1-1
:end-before: -- use1-2

.. rubric:: Case 3

When source and/or target belong to a vertex then a path is not found.

In this case, the contracted graph do not have an edge connecting with
node :math:`7` and of node :math:`4` of the second case.

.. literalinclude:: contraction-family.queries
:start-after: -- use1-2
:end-before: -- case2

Case 2: Source and/or target belong to an edge subgraph.
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Refining the above function to include nodes that belong to an edge.

- The vertices that need to be expanded are calculated on lines 11 to 17.
- Adding to the contracted graph that additional section on lines 26 to 28.

.. literalinclude:: contraction-family.queries
:emphasize-lines: 11-17, 26-28
:start-after: -- case2
:end-before: -- use2
:linenos:

.. rubric:: Case 1

When both source and target belong to the contracted graph, a path is found.

.. literalinclude:: contraction-family.queries
:start-after: -- use2
:end-before: -- use2-1

.. rubric:: Case 2

When source and/or target belong to an edge subgraph, now, a path is found.

The routing graph now has an edge connecting with node :math:`4`.

.. literalinclude:: contraction-family.queries
:start-after: -- use2-1
:end-before: -- use2-2

.. rubric:: Case 3

When source and/or target belong to a vertex then a path is not found.

In this case, the contracted graph do not have an edge connecting with
node :math:`7`.

.. literalinclude:: contraction-family.queries
:start-after: -- use2-2
:end-before: -- case3

Case 3: Source and/or target belong to a vertex.
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Refining the above function to include nodes that belong to an edge.

- The vertices that need to be expanded are calculated on lines 19 to 24.
- Adding to the contracted graph that additional section on lines 38 to 40.

.. literalinclude:: contraction-family.queries
:emphasize-lines: 19-24, 39-41
:start-after: -- case3
:end-before: -- use3
:linenos:

.. rubric:: Case 1

When both source and target belong to the contracted graph, a path is found.

.. literalinclude:: contraction-family.queries
:start-after: -- use3
:end-before: -- use3-1

.. rubric:: Case 2

The code change do not affect this case so when source and/or target belong
to an edge subgraph, a path is still found.

.. literalinclude:: contraction-family.queries
:start-after: -- use3-1
:end-before: -- use3-2

.. rubric:: Case 3

When source and/or target belong to a vertex, now, a path is found.

Now, the routing graph has an edge connecting with node :math:`7`.

.. literalinclude:: contraction-family.queries
:start-after: -- use3-2
:end-before: -- end

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

Expand Down
Loading