New function : pgr maxWeightedMatching

NEWS.md

@@ -34,9 +34,18 @@ To see all issues & pull requests closed by this release see the
 
 * [#3101](https://github.com/pgRouting/pgrouting/issues/3101): pgr_edgeColoring not building graph correctly
 
+**New experimental functions.**
+
+* Flow
+
+  * :issue:3136: pgr_maxWeightedMatching
 
 **Summary of changes by function**
 
+* pgr_maxWeightedMatching
+
+  * New experimental function.
+
 * pgr_edgeColoring
 
   * Fix the way it builds the graph

doc/_static/page_history.js

@@ -16,6 +16,8 @@ var titles = [
 
 
 var newpages = [
+    {v: '4.1', pages: ['pgr_maxWeightedMatching']},
+
     {v: '4.0', pages: ['pgr_bandwidth', 'pgr_kingOrdering', 'pgr_sloanOrdering']},
 
     {v: '3.8', pages: ['pgr_contractionDeadEnd', 'pgr_contractionLinear', 'pgr_separateCrossing',

doc/max_flow/CMakeLists.txt

@@ -11,6 +11,7 @@ set(LOCAL_FILES
     pgr_maxCardinalityMatch.rst
     pgr_pushRelabel.rst
     pgr_maxFlowMinCost.rst
+    pgr_maxWeightedMatching.rst
     # TODO rename
     pgr_maxFlowMinCost_Cost.rst
     )
@@ -22,3 +23,7 @@ endforeach()
 
 set(PROJECT_DOC_FILES ${PROJECT_DOC_FILES} ${LOCAL_DOC_FILES} PARENT_SCOPE)
 
+add_subdirectory("images")
+set(PROJECT_IMG_FILES ${PROJECT_IMG_FILES} PARENT_SCOPE)
+
+

doc/max_flow/flow-family.rst

@@ -36,6 +36,8 @@ Flow - Family of functions
 
 * :doc:`pgr_maxFlowMinCost` - Details of flow and cost on edges.
 * :doc:`pgr_maxFlowMinCost_Cost` - Only the Min Cost calculation.
+* :doc:`pgr_maxWeightedMatching` - Calculates a maximum weighted matching in a
+  graph.
 
 .. experimental-end
 
@@ -50,6 +52,7 @@ Flow - Family of functions
     pgr_maxCardinalityMatch
     pgr_maxFlowMinCost
     pgr_maxFlowMinCost_Cost
+    pgr_maxWeightedMatching
 
 
 Flow Functions General Information

doc/max_flow/images/CMakeLists.txt

@@ -0,0 +1,15 @@
+# This file is part of the pgRouting project.
+# Copyright (c) 2017-2026 pgRouting developers
+# License: GPL-2 See https://github.com/pgRouting/pgrouting/blob/main/LICENSE
+
+set(LOCAL_FILES
+    mwm_graph.png
+    mwm_result.png
+    )
+
+foreach (f ${LOCAL_FILES})
+    configure_file(${f} "${PGR_DOCUMENTATION_SOURCE_DIR}/images/${f}" COPYONLY)
+    list(APPEND LOCAL_IMG_FILES  "${PGR_DOCUMENTATION_SOURCE_DIR}/images/${f}")
+endforeach()
+
+set(PROJECT_IMG_FILES ${PROJECT_IMG_FILES} ${LOCAL_IMG_FILES} PARENT_SCOPE)

doc/max_flow/pgr_maxWeightedMatching.rst

@@ -0,0 +1,179 @@
+:file: This file is part of the pgRouting project.
+:copyright: Copyright (c) 2020-2026 pgRouting developers
+:license: Creative Commons Attribution-Share Alike 3.0 https://creativecommons.org/licenses/by-sa/3.0
+
+.. index::
+   single: Flow Family ; pgr_maxWeightedMatching - Experimental
+   single: maxWeightedMatching - Experimental on v4.1
+
+|
+
+``pgr_maxWeightedMatching`` - Experimental
+===============================================================================
+
+``pgr_maxWeightedMatching`` — Calculates a maximum weighted matching in a graph.
+
+.. include:: experimental.rst
+   :start-after: warning-begin
+   :end-before: end-warning
+
+.. rubric:: Availability
+
+.. rubric:: Version 4.1.0
+
+* New experimental function.
+
+
+Description
+-------------------------------------------------------------------------------
+
+A **maximum weighted matching** in a graph is a matching where the sum of the
+weights of selected edges is maximized.
+
+A matching or independent edge set in a graph is a set of edges without common
+vertices.
+
+The main characteristics are:
+
+- Works for **undirected** graphs.
+- Each vertex is matched with at most one other vertex.
+- Maximizes the total edge weight sum.
+- There may be many maximum weighted matchings.
+
+  - Calculates one possible maximum weighted matching in a graph.
+
+- Returns the matched pairs of vertices in the form of a set of
+  `(start_vid, end_vid, agg_cost)`.
+
+  - `start_vid` and `end_vid` are the endpoints of the matched edge.
+  - `agg_cost` is the weight of the matched edge.
+
+- For the undirected graph, the results are symmetric.
+
+  - The `agg_cost` of `(u, v)` is the same as for `(v, u)`.
+
+- Running time: :math:`O(n^3)` where :math:`n` is the number of vertices.
+
+|Boost| Boost Graph Inside
+
+Signatures
+-------------------------------------------------------------------------------
+
+.. rubric:: Summary
+
+.. admonition:: \ \
+   :class: signatures
+
+   | pgr_maxWeightedMatching(`Edges SQL`_, ``directed``)
+
+   | Returns set of |matrix-result|
+   | OR EMPTY SET
+
+:Example: Using all edges.
+
+.. literalinclude:: maxWeightedMatching.queries
+   :start-after: -- q1
+   :end-before: -- q2
+
+Parameters
+-------------------------------------------------------------------------------
+
+.. include:: allpairs-family.rst
+    :start-after: edges_start
+    :end-before: edges_end
+
+Optional parameters
+...............................................................................
+
+.. list-table::
+   :width: 81
+   :widths: auto
+   :header-rows: 1
+
+   * - Column
+     - Type
+     - Default
+     - Description
+   * - ``directed``
+     - ``BOOLEAN``
+     - ``false``
+     - Ignored. The matching algorithm always works on **undirected** graphs.
+
+Inner Queries
+-------------------------------------------------------------------------------
+
+Edges SQL
+...............................................................................
+
+.. include:: pgRouting-concepts.rst
+    :start-after: basic_edges_sql_start
+    :end-before: basic_edges_sql_end
+
+Result columns
+-------------------------------------------------------------------------------
+
+Set of |matrix-result|
+
+.. list-table::
+   :width: 81
+   :widths: 12 14 60
+   :header-rows: 1
+
+   * - Column
+     - Type
+     - Description
+   * - ``start_vid``
+     - ``BIGINT``
+     - Identifier of the first end point vertex of the matched edge.
+   * - ``end_vid``
+     - ``BIGINT``
+     - Identifier of the second end point vertex of the matched edge.
+   * - ``agg_cost``
+     - ``FLOAT``
+     - Weight of the matched edge.
+
+Additional Examples
+-------------------------------------------------------------------------------
+
+.. raw:: html
+
+   <table style="width:100%; border:none; border-collapse:collapse;">
+     <tr>
+       <td style="width:50%; text-align:center; padding:8px; border:none;">
+         <strong>Before Matching</strong><br/>
+         <img src="_images/mwm_graph.png" alt="Sample graph before maximum weighted matching" style="max-width:100%;"/>
+         <p><em>Sample graph with 5 vertices and 6 weighted edges before matching.</em></p>
+       </td>
+       <td style="width:50%; text-align:center; padding:8px; border:none;">
+         <strong>After Matching</strong><br/>
+         <img src="_images/mwm_result.png" alt="Sample graph after maximum weighted matching" style="max-width:100%;"/>
+         <p><em>Graph after maximum weighted matching: selected edges are highlighted.</em></p>
+       </td>
+     </tr>
+   </table>
+
+.. image:: images/mwm_graph.png
+   :width: 0
+
+.. image:: images/mwm_result.png
+   :width: 0
+
+:Example: Maximum weighted matching on a custom 5-vertex graph.
+
+.. literalinclude:: maxWeightedMatching.queries
+   :start-after: -- q2
+   :end-before: -- q4
+
+
+See Also
+-------------------------------------------------------------------------------
+
+* :doc:`flow-family`
+* :doc:`sampledata`
+* `Boost: maximum_weighted_matching
+  <https://www.boost.org/doc/libs/latest/libs/graph/doc/maximum_weighted_matching.html>`__
+
+.. rubric:: Indices and tables
+
+* :ref:`genindex`
+* :ref:`search`

doc/src/pgRouting-introduction.rst

@@ -139,6 +139,7 @@ Jinfu Leng,
 Kai Behncke,
 Kishore Kumar,
 Ko Nagase,
+Mayur Galhate,
 Mahmoud Sakr,
 Manikata Kondeti,
 Mario Basa,

doc/src/release_notes.rst

@@ -59,9 +59,20 @@ To see all issues & pull requests closed by this release see the
 
 * :issue:`3101`: pgr_edgeColoring not building graph correctly
 
+.. rubric:: New experimental functions.
+
+* Flow
+
+  * :issue:3136: pgr_maxWeightedMatching
 
 .. rubric:: Summary of changes by function
 
+* pgr_maxWeightedMatching
+
+  .. include:: pgr_maxWeightedMatching.rst
+     :start-after: Version 4.1.0
+     :end-before: Description
+
 * pgr_edgeColoring
 
   .. include:: pgr_edgeColoring.rst

docqueries/max_flow/CMakeLists.txt

@@ -11,6 +11,7 @@ set(LOCAL_FILES
     pushRelabel
     maxFlowMinCost
     maxFlowMinCost_Cost
+    maxWeightedMatching
 
     )
 

docqueries/max_flow/maxWeightedMatching.pg

@@ -0,0 +1,31 @@
+/* :file: This file is part of the pgRouting project.
+:copyright: Copyright (c) 2016-2026 pgRouting developers
+:license: Creative Commons Attribution-Share Alike 3.0 https://creativecommons.org/licenses/by-sa/3.0 */
+/* -- q1 */
+SELECT * FROM pgr_maxWeightedMatching(
+  'SELECT id, source, target, cost FROM edges',
+  false
+);
+
+/* -- q2 */
+CREATE TABLE additional_sample_1 (
+    id SERIAL PRIMARY KEY,
+    source INTEGER,
+    target INTEGER,
+    cost DOUBLE PRECISION,
+    reverse_cost DOUBLE PRECISION
+);
+
+INSERT INTO additional_sample_1 (source, target, cost, reverse_cost) VALUES
+(1, 2, 5, 5),
+(2, 3, 1, 1),
+(1, 3, 2, 2),
+(2, 4, 4, 4),
+(4, 5, 3, 3),
+(3, 5, 6, 6);
+SELECT * FROM pgr_maxWeightedMatching(
+    'SELECT id, source, target, cost, reverse_cost FROM additional_sample_1',
+    false
+);
+
+/* -- q4 */

docqueries/max_flow/maxWeightedMatching.result

@@ -0,0 +1,54 @@
+BEGIN;
+BEGIN
+SET client_min_messages TO NOTICE;
+SET
+/* :file: This file is part of the pgRouting project.
+:copyright: Copyright (c) 2016-2026 pgRouting developers
+:license: Creative Commons Attribution-Share Alike 3.0 https://creativecommons.org/licenses/by-sa/3.0 */
+/* -- q1 */
+SELECT * FROM pgr_maxWeightedMatching(
+  'SELECT id, source, target, cost FROM edges',
+  false
+);
+ start_vid | end_vid | agg_cost
+-----------+---------+----------
+         2 |       4 |        1
+         5 |       6 |        2
+         3 |       7 |        3
+         8 |       9 |        4
+        10 |      11 |        5
+        13 |      14 |        6
+        15 |      16 |        7
+        12 |      17 |        8
+(8 rows)
+
+/* -- q2 */
+CREATE TABLE additional_sample_1 (
+    id SERIAL PRIMARY KEY,
+    source INTEGER,
+    target INTEGER,
+    cost DOUBLE PRECISION,
+    reverse_cost DOUBLE PRECISION
+);
+CREATE TABLE
+INSERT INTO additional_sample_1 (source, target, cost, reverse_cost) VALUES
+(1, 2, 5, 5),
+(2, 3, 1, 1),
+(1, 3, 2, 2),
+(2, 4, 4, 4),
+(4, 5, 3, 3),
+(3, 5, 6, 6);
+INSERT 0 6
+SELECT * FROM pgr_maxWeightedMatching(
+    'SELECT id, source, target, cost, reverse_cost FROM additional_sample_1',
+    false
+);
+ start_vid | end_vid | agg_cost
+-----------+---------+----------
+         1 |       2 |        5
+         3 |       5 |       11
+(2 rows)
+
+/* -- q4 */
+ROLLBACK;
+ROLLBACK

docqueries/max_flow/test.conf

@@ -14,6 +14,7 @@
             edgeDisjointPaths.pg
             maxFlowMinCost.pg
             maxFlowMinCost_Cost.pg
+            maxWeightedMatching.pg
             )]
     },
 );

include/c_common/enums.h

@@ -52,6 +52,8 @@ enum Which {  // NOLINT(cppcoreguidelines-use-enum-class)
     MAXFLOW, PUSHRELABEL, BOYKOV, EDMONDSKARP,
     /* For coloring */
     EDGECOLORING, BIPARTITE, SEQUENTIAL,
+    /* For Matching */
+    MAXWEIGHTEDMATCHING,
     /* For components */
     CONNECTEDCOMPONENTS, BICONNECTEDCOMPONENTS, STRONGCOMPONENTS, ARTICULATIONPOINTS,
     BRIDGES, MAKECONNECTED