New code for pgr_hawickCircuits

NEWS.md

@@ -36,6 +36,13 @@ To see all issues & pull requests closed by this release see the
 
   * Fix the way it builds the graph
 
+* pgr_hawickCircuits
+
+  * New optional parameters: ``min_depth``, ``max_depth``, ``self_loops`` and
+    ``u_turn_on_edge``.
+  * New signatures to select starting vertices.
+  * Deprecated signature: ``pgr_hawickCircuits(text)``.
+
 * pgr_makeBiconnectedPlanar
 
   * New experimental function.
@@ -74,6 +81,7 @@ To see all issues & pull requests closed by this release see the
   process/driver pair
 * [#3154](https://github.com/pgRouting/pgrouting/issues/3154): betweennessCentrality: use allpairs/process and driver
 * [#3163](https://github.com/pgRouting/pgrouting/issues/3163): KSP & KSP WithPoints Use ShortestPath driver files
+* [#3170](https://github.com/pgRouting/pgrouting/issues/3170): pgr_hawickCircuits: wrong  function referenced
 
 4.1.0 Bug Fixes
 

doc/_static/page_history.js

@@ -17,7 +17,7 @@ var titles = [
 
 var newpages = [
     {v: '4.1', pages: ['pgr_coreNumbers', 'pgr_planarFaces', 'planar-family', 'pgr_makeBiconnectedPlanar',
-        'pgr_maxWeightedMatch']},
+        'pgr_maxWeightedMatch', 'circuits-family']},
 
     {v: '4.0', pages: ['pgr_bandwidth', 'pgr_kingOrdering', 'pgr_sloanOrdering']},
 

doc/circuits/CMakeLists.txt

@@ -3,8 +3,9 @@
 # License: GPL-2 See https://github.com/pgRouting/pgrouting/blob/main/LICENSE
 
 set(LOCAL_FILES
+    circuits-family.rst
     pgr_hawickCircuits.rst
-    )
+)
 
 foreach (f ${LOCAL_FILES})
     configure_file(${f} "${PGR_DOCUMENTATION_SOURCE_DIR}/${f}")

doc/circuits/circuits-family.rst

@@ -0,0 +1,178 @@
+:file: This file is part of the pgRouting project.
+:copyright: Copyright (c) 2022-2026 pgRouting developers
+:license: Creative Commons Attribution-Share Alike 3.0 https://creativecommons.org/licenses/by-sa/3.0
+
+
+.. index:: Circuits Family
+
+|
+
+Circuits - Family of Functions
+===============================================================================
+
+The following functions work on circuits of directed graphs.
+
+.. include:: experimental.rst
+   :start-after: warning-begin
+   :end-before: end-warning
+
+.. experimental-start
+
+* :doc:`pgr_hawickCircuits` - Hawick's circuits algorithm.
+
+.. experimental-end
+
+.. toctree::
+    :hidden:
+
+    pgr_hawickCircuits
+
+Description
+-------------------------------------------------------------------------------
+
+Parameters
+-------------------------------------------------------------------------------
+
+.. circuits_parameters_start
+
+.. list-table::
+   :width: 81
+   :widths: 10,15,40
+   :header-rows: 1
+
+   * - Parameter
+     - Type
+     - Description
+   * - `Edges SQL`_
+     - ``TEXT``
+     - `Edges SQL`_ as described below.
+   * - ``start vid``
+     - |ANY-INTEGER|
+     - A vertex of the circuits:
+       - All the circuits that contain the vertex are returned.
+       - When ``0`` all the circuits are returned in canonical order.
+   * - ``start vids``
+     - ``ARRAY[`` |ANY-INTEGER| ``]``
+     - Vertices of the circuits: for each requested vertex:
+       - All the circuits that contain the vertex are returned:
+       - When empty all the circuits are returned in canonical order.
+
+
+.. circuits_parameters_end
+
+Optional parameters
+...............................................................................
+
+.. circuits_optionals_start
+
+.. list-table::
+   :width: 81
+   :widths: auto
+   :header-rows: 1
+
+   * - Parameter
+     - Type
+     - Default
+     - Description
+   * - ``min_depth``
+     - ``BIGINT``
+     - ``1``
+     - Minimum number of vertices in a circuit.
+       * Exclude 2 edge circuits by increasing this number.
+   * - ``max_depth``
+     - ``BIGINT``
+     - ``9223372036854775807``
+     - Maximum number of vertices in a circuit.
+   * - ``self_loops``
+     - ``BOOLEAN``
+     - ``true``
+     - * When ``true`` self loops are included in the results.
+       * When ``false`` self loops are excluded from the results.
+       * Self loops are included or excluded regardless of ``min_depth`` and ``max_depth``.
+   * - ``u_turn_on_edge``
+     - ``BOOLEAN``
+     - ``true``
+     - * A u-turn on an edge is a 2 edge circuit that uses the same ``id`` on
+         both directions of the edge.
+       * When ``true``: u-turns are part of the results.
+       * When ``false``: u-turns are discarded when the circuit can be formed
+         with two different edges; a u-turn is kept when it is the only
+         option, that is, when the two vertices are connected by a single
+         edge.
+       * Self loops are not affected.
+
+.. circuits_optionals_end
+
+Inner Queries
+-------------------------------------------------------------------------------
+
+Edges SQL
+...............................................................................
+
+.. include:: pgRouting-concepts.rst
+    :start-after: basic_edges_sql_start
+    :end-before: basic_edges_sql_end
+
+Result columns
+-------------------------------------------------------------------------------
+
+.. circuits_result_columns_start
+
+.. 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``
+   * - ``depth``
+     - ``INTEGER``
+     - Relative position in the circuit. Has value **0** for the beginning of a
+       circuit
+   * - ``start_vid``
+     - ``BIGINT``
+     - Identifier of the starting vertex of the circuit.
+   * - ``end_vid``
+     - ``BIGINT``
+     - Identifier of the ending vertex of the circuit.
+   * - ``pred``
+     - ``BIGINT``
+     - Identifier of the node that precedes ``node`` in the circuit.
+
+       - When ``node`` is the first node of the circuit, it has the same value
+         as ``node``.
+   * - ``node``
+     - ``BIGINT``
+     - Identifier of the node in the path from a vid to next vid.
+   * - ``edge``
+     - ``BIGINT``
+     - Identifier of the edge used to arrive from ``pred`` to ``node``.
+       - ``-1`` when :math:`depth = 0`.
+   * - ``cost``
+     - ``FLOAT``
+     - Cost to traverse from ``pred`` to ``node`` using ``edge``.
+       - ``0`` when :math:`depth = 0`.
+   * - ``agg_cost``
+     - ``FLOAT``
+     - Aggregate cost from ``start_vid`` to ``node``.
+
+.. circuits_result_columns_end
+
+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`