Added New Hypergraph Matching Algorithms

[rotshira]

This pull request introduces several enhancements and new features to the HyperNetX library:

1. New Matching Algorithms:

   • Implemented three new hypergraph matching algorithms that provide better approximations than the greedy matching algorithm.
   • Each algorithm accepts an additional parameter for a custom maximum matching function, allowing for flexibility in usage.

2. Iterated Sampling Algorithm:

   • An implementation of the iterated sampling algorithm for hypergraph matching. This algorithm uses a probabilistic approach to find an approximate matching in hypergraphs.

3. HEDCS-Based Approximation Algorithm:

   • Added the HEDCS-based approximation algorithm for hypergraph matching. This algorithm constructs a Hyper-Edge Degree Constrained Subgraph (HEDCS) to find a maximal matching.

4. Greedy Matching Algorithm:

   • Enhanced the greedy matching algorithm to be more efficient and scalable.

5. Logging and Debugging:

   • Added extensive logging to all algorithms to aid in debugging and performance analysis.

6. Experiments and Performance Comparison:

   • Created scripts to run performance comparisons of the algorithms on large random inputs using the experiments_csv library.
   • Generated and analyzed results to compare the size of the match and the running time of each algorithm.

Testing:

• Thoroughly tested the new algorithms with various input sizes and configurations.
• Added doctests to ensure the correctness and robustness of the algorithms.

Documentation:

• Updated the documentation to include descriptions and usage examples for the new algorithms.

Instructions for Reviewers:

• Please review the new algorithms for correctness and performance.
• Verify the logging outputs for clarity and usefulness.

Thank you for considering this contribution to the HyperNetX library.

[nivmoti]

hey we just added a Python tutorial in tutorials/advanced/
we still get the error in the workflow that @erelsgl mentioned last week.

[myersau3]

Hi @rotshira! Thank you for your contribution! It is very thorough and impressive. We are excited to get it implemented into HNX as a module. It seems that you have all the necessary files for us to put in a new module. The exact process (contribution guidelines) for the needed files and changes for us to review in a PR is documented here https://hypernetx.readthedocs.io/en/develop/contributions.html. If you could go over those contribution guidelines and resubmit the PR with just the needed files it would be appreciated. Specifically, we are looking for just the module (.py) file itself, a tutorial as a notebook, and a unit test file. If you would also like to provide an rst file for the documentation that would be great! specifically something like what was done for Modularity and Clustering (https://hypernetx.readthedocs.io/en/develop/modularity.html). Thank you again!

[erelsgl]

Move the fast algorithm into matching_algorithms.py and remove this file

[erelsgl]

This file should not appear as changed. Copy&paste the original version; make sure all spaces are the same.

[nivmoti]

We have implemented the requested changes and completed the following additions and updates, We have updated the init.py file in hypernetx/algorithms/ to include imports for the new functions.

[nivmoti]

add the Matching Algorithm API

[erelsgl]

@myersau3 are there any other required changes?

[myersau3]

@myersau3 are there any other required changes?

@erelsgl So far this looks good to me! Thank you for making those changes! I'm going to go through everything in detail today and will get back to you soon if anything needs changed.

[myersau3]

@erelsgl @nivmoti @rotshira I've created a branch called "hypergraph_matching" that I will be using to submit a PR for this module. I had to make a few minor changes to be compatible with our current format but overall everything looks good and runs! Thank you for all the work. I'll make sure that you all are credited with the contributions and will keep you updated! Thank you again!

[brendapraggastis]

@myersau3 If this issue is resolved, please close it. thanks