Introduced the class MatchingCoveredGraph

[janmenjayap]

The objective of this issue is to introduce a new class MatchingCoveredGraph through a new file src/sage/graphs/matching_covered_graph.py in order to address the decompositions, generation methods and related concepts in the theory of Matching Covered Graphs.

This PR introduces a new class pertaining to matching, namely MatchingCoveredGraph and aims to list out all functions fundamentally related to matching covered graph in the file src/sage/graphs/matching_covered_graph.py. The initialization and some basic class methods in this context, that shall be addressed through this PR, are described below:

• __init__(): Create a matching covered graph, that is a connected nontrivial graph wherein each edge participates in some perfect matching.
• __repr__(): Return a short string representation of the matching covered graph.
• _subgraph_by_adding(): Return the matching covered subgraph containing the given vertices and edges.
• _upgrade_from_graph(): Upgrade the given graph to a matching covered graph if eligible.
• add_edge(): Add an edge from vertex u to vertex v.
• add_edges(): Add edges from an iterable container.
• add_vertex(): Add a vertex to the (matching covered) graph.
• add_vertices(): Add vertices to the (matching covered) graph from an iterable container of vertices.
• allow_loops(): Change whether loops are allowed in (matching covered) graphs.
• allows_loops(): Return whether loops are permitted in (matching covered) graph.
• delete_vertex(): Delete a vertex, removing all incident edges.0
• delete_vertices(): Delete specified vertices form self.
• get_matching(): Return a :class:~EdgesView of self._matching (a perfect matching of the (matching covered) graph computed at the initialization).
• has_perfect_matching(): Return whether the graph has a perfect matching.
• update_matching(): Update the perfect matching captured in self._matching.

This PR shall establish a foundation to address the methods related to matching covered graphs.

Fixes #38216.
Note that this issue fixes a small part of the above-mentioned issue.

📝 Checklist

• The title is concise and informative.
• The description explains in detail what this PR is about.
• I have linked a relevant issue or discussion.
• I have created tests covering the changes.
• I have updated the documentation and checked the documentation preview.

⌛ Dependencies

Nothing as of now (up to my knowledge).

cc: @dcoudert.

[janmenjayap]

Hi,
I have a doubt. the class MatchingCoveredGraph inherits the class Graph and the class Graph inherits the class GenericGraph. Still the class MatchingCoveredGraph is not able to access some private members of the class GenericGraph such as self._backend, as a consequence of which the following test case does not pass. In fact, creating an object of the class MatchingCoveredGraph throws error:

sage: G = graphs.CompleteGraph(4)
sage: H = MatchingCoveredGraph(G)
---------------------------------------------------------------------------
AttributeError                            Traceback (most recent call last)
<ipython-input-2-d169ce49e91a> in ?()
----> 1 H = MatchingCoveredGraph(G)

~/open-source/sage/src/sage/graphs/matching_covered_graph.py in ?(self, data, matching, algorithm, solver, verbose, integrality_tolerance, *args, **kwds)
    396         elif isinstance(data, MatchingCoveredGraph):
    397             Graph.__init__(self, data, *args, **kwds)
    398 
    399         else:
--> 400             self._upgrade_from_graph(matching, algorithm, solver, verbose,
    401                                      integrality_tolerance)
    402 
    403         del self.allow_loops

~/open-source/sage/src/sage/graphs/matching_covered_graph.py in ?(self, matching, algorithm, solver, verbose, integrality_tolerance)
    419 
    420             if not check:
    421                 raise ValueError("input graph is not matching covered")
    422 
--> 423         except ValueError as error:
    424             raise error

~/open-source/sage/src/sage/graphs/matching.py in ?(G, matching, algorithm, coNP_certificate, solver, verbose, integrality_tolerance)
    960     AUTHORS:
    961 
    962     - Janmenjaya Panda (2024-06-23)
    963     """
--> 964     G._scream_if_not_simple(allow_multiple_edges=True)
    965 
    966     # The graph must be nontrivial
    967     if G.order() < 2:

~/open-source/sage/src/sage/graphs/generic_graph.py in ?(self, allow_loops, allow_multiple_edges)
   1481             Traceback (most recent call last):
   1482             ...
   1483             ValueError: This method is not known to work on graphs with loops. Perhaps this method can be updated to handle them, but in the meantime if you want to use it please disallow loops using allow_loops().
   1484         """
-> 1485         pb_with_loops = not allow_loops and self.allows_loops()
   1486         pb_with_multiple_edges = not allow_multiple_edges and self.allows_multiple_edges()
   1487         if pb_with_loops or pb_with_multiple_edges:
   1488             if pb_with_loops and pb_with_multiple_edges:

~/open-source/sage/src/sage/graphs/generic_graph.py in ?(self)
   3279             False
   3280             sage: D.edges(sort=True)
   3281             []
   3282         """
-> 3283         return self._backend.loops(None)

AttributeError: 'MatchingCoveredGraph' object has no attribute '_backend'

A comment on this would be highly appreciated.
Thank you.

[dcoudert]

Check src/sage/graphs/bipartite_graph.py.

[github-actions]

Documentation preview for this PR (built with commit c63a2bb; changes) is ready! 🎉
This preview will update shortly after each push to this PR.

[janmenjayap]

Hi,
Could you please mention the requirement of * in the method matching() in src/sage/graphs/matching.py.

Actually, the errors in the test cases that are coming up, I suppose due to the use of * in the method is_matching_covered() in src/sage/graphs/matching.py.

Thank you.

[janmenjayap]

Hi, Could you please mention the requirement of * in the method matching() in src/sage/graphs/matching.py.

Actually, the errors in the test cases that are coming up, I suppose due to the use of * in the method is_matching_covered() in src/sage/graphs/matching.py.

Thank you.

I have rectified the errors caused in matching_covered_graph.py without changing anything in matching.py.

[dcoudert]

The * in the list of parameters means that the parameters placed after the * must be explicitly named.

sage: def foo(a=1, b=2, *, c=3):
....:     return a + b + c
sage: foo()
6
sage: foo(7)
12
sage: foo(7, 8)
18
sage: foo(7, 8, 9)
---------------------------------------------------------------------------
TypeError                                 Traceback (most recent call last)
Cell In[7], line 1
----> 1 foo(Integer(7), Integer(8), Integer(9))

TypeError: foo() takes from 0 to 2 positional arguments but 3 were given
sage: foo(7, 8, c=9)
24
sage: foo(a=10)
15
sage: foo(b=10)
14
sage: foo(c=10)
13
sage: foo(b=20, c=10)
31

[dcoudert]

Now that we have this class, what happens if I add/remove a vertex or an edge ?
You should certainly adapt methods modifying the graph to ensure that a modified graph remains in the class and otherwise raise an error without modifying the graph.

[dcoudert]

LGTM.

[janmenjayap]

Thank you.