adding_HG_matching code, tests, rst, and notebook

docs/source/algorithms/matching_algorithms.rst

@@ -0,0 +1,61 @@
+Matching Algorithms for Hypergraphs
+===================================
+
+Introduction
+------------
+This module implements various algorithms for finding matchings in hypergraphs. These algorithms are based on the methods described in the paper:
+
+*Distributed Algorithms for Matching in Hypergraphs* by Oussama Hanguir and Clifford Stein.
+
+The paper addresses the problem of finding matchings in d-uniform hypergraphs, where each hyperedge contains exactly d vertices. The matching problem is NP-complete for d ≥ 3, making it one of the classic challenges in computational theory. The algorithms described here are designed for the Massively Parallel Computation (MPC) model, which is suitable for processing large-scale hypergraphs.
+
+Mathematical Foundation
+------------------------
+The algorithms in this module provide different trade-offs between approximation ratios, memory usage, and computation rounds:
+
+1. **O(d²)-approximation algorithm**:
+   - This algorithm partitions the hypergraph into random subgraphs and computes a matching for each subgraph. The results are combined to obtain a matching for the original hypergraph.
+   - Approximation ratio: O(d²)
+   - Rounds: 3
+   - Memory: O(√nm)
+
+2. **d-approximation algorithm**:
+   - Uses sampling and post-processing to iteratively build a maximal matching.
+   - Approximation ratio: d
+   - Rounds: O(log n)
+   - Memory: O(dn)
+
+3. **d(d−1 + 1/d)²-approximation algorithm**:
+   - Utilizes the concept of HyperEdge Degree Constrained Subgraphs (HEDCS) to find an approximate matching.
+   - Approximation ratio: d(d−1 + 1/d)²
+   - Rounds: 3
+   - Memory: O(√nm) for linear hypergraphs, O(n√nm) for general cases.
+
+These algorithms are crucial for applications that require scalable parallel processing, such as combinatorial auctions, scheduling, and multi-agent systems.
+
+Usage Example
+-------------
+Below is an example of how to use the matching algorithms module.
+
+```python
+from hypernetx.algorithms import matching_algorithms as ma
+
+# Example hypergraph data
+hypergraph = ... # Assume this is a d-uniform hypergraph
+
+# Compute a matching using the O(d²)-approximation algorithm
+matching = ma.matching_approximation_d_squared(hypergraph)
+
+# Compute a matching using the d-approximation algorithm
+matching_d = ma.matching_approximation_d(hypergraph)
+
+# Compute a matching using the d(d−1 + 1/d)²-approximation algorithm
+matching_d_squared = ma.matching_approximation_dd(hypergraph)
+
+print(matching, matching_d, matching_d_squared)
+
+
+References
+-------------
+
+- Oussama Hanguir, Clifford Stein, Distributed Algorithms for Matching in Hypergraphs, https://arxiv.org/pdf/2009.09605