gh-37340: Add class FlatsMatroid
    
This matroid subclass allows the definition and internal representation
of a matroid based on its flats (closed sets). This representation can
be advantageous for some algorithms. This completes the list of the most
standard matroid definitions (bases, circuits, flats, rank function).

This PR is similar to #37148.

- [x] The title is concise, informative, and self-explanatory.
- [x] The description explains in detail what this PR is about.
- [x] I have linked a relevant issue or discussion.
- [x] I have created tests covering the changes.
- [x] I have updated the documentation accordingly.
    
URL: #37340
Reported by: gmou3
Reviewer(s): gmou3, Matthias Köppe

Author: Release Manager

src/doc/en/reference/matroids/index.rst

@@ -29,6 +29,7 @@ Concrete implementations
    sage/matroids/basis_matroid
    sage/matroids/circuits_matroid
    sage/matroids/circuit_closures_matroid
+   sage/matroids/flats_matroid
    sage/matroids/linear_matroid
    sage/matroids/rank_matroid
    sage/matroids/graphic_matroid

src/sage/matroids/advanced.py

@@ -15,6 +15,7 @@
         - :class:`RankMatroid <sage.matroids.rank_matroid.RankMatroid>`
         - :class:`CircuitClosuresMatroid <sage.matroids.circuit_closures_matroid.CircuitClosuresMatroid>`
         - :class:`BasisMatroid <sage.matroids.basis_matroid.BasisMatroid>`
+        - :class:`FlatsMatroid <sage.matroids.flats_matroid.FlatsMatroid>`
         - :class:`LinearMatroid <sage.matroids.linear_matroid.LinearMatroid>`
         - :class:`RegularMatroid <sage.matroids.linear_matroid.RegularMatroid>`
         - :class:`BinaryMatroid <sage.matroids.linear_matroid.BinaryMatroid>`
@@ -54,6 +55,7 @@
 from .rank_matroid import RankMatroid
 from .circuit_closures_matroid import CircuitClosuresMatroid
 from .basis_matroid import BasisMatroid
+from .flats_matroid import FlatsMatroid
 from .linear_matroid import LinearMatroid, RegularMatroid, BinaryMatroid, TernaryMatroid, QuaternaryMatroid
 from .utilities import setprint, newlabel, get_nonisomorphic_matroids, lift_cross_ratios, lift_map
 from . import lean_matrix

src/sage/matroids/constructor.py

@@ -113,6 +113,7 @@
 import sage.matroids.basis_exchange_matroid
 from .rank_matroid import RankMatroid
 from .circuits_matroid import CircuitsMatroid
+from .flats_matroid import FlatsMatroid
 from .circuit_closures_matroid import CircuitClosuresMatroid
 from .basis_matroid import BasisMatroid
 from .linear_matroid import LinearMatroid, RegularMatroid, BinaryMatroid, TernaryMatroid, QuaternaryMatroid
@@ -178,8 +179,9 @@ def Matroid(groundset=None, data=None, **kwds):
       matroid.
     - ``independent_sets`` -- The list of independent sets of the matroid.
     - ``circuits`` -- The list of circuits of the matroid.
-    - ``nonspanning_circuits`` -- The list of nonspanning_circuits of the
+    - ``nonspanning_circuits`` -- The list of nonspanning circuits of the
       matroid.
+    - ``flats`` -- The dictionary of flats indexed by their rank.
     - ``graph`` -- A graph, whose edges form the elements of the matroid.
     - ``matrix`` -- A matrix representation of the matroid.
     - ``reduced_matrix`` -- A reduced representation of the matroid: if
@@ -224,6 +226,8 @@ def Matroid(groundset=None, data=None, **kwds):
 
         The ``Matroid()`` method will return instances of type
         :class:`BasisMatroid <sage.matroids.basis_matroid.BasisMatroid>`,
+        :class:`CircuitsMatroid <sage.matroids.circuits_matroid.CircuitsMatroid>`,
+        :class:`FlatsMatroid <sage.matroids.flats_matroid.FlatsMatroid>`,
         :class:`CircuitClosuresMatroid <sage.matroids.circuit_closures_matroid.CircuitClosuresMatroid>`,
         :class:`LinearMatroid <sage.matroids.linear_matroid.LinearMatroid>`,
         :class:`BinaryMatroid <sage.matroids.linear_matroid.LinearMatroid>`,
@@ -305,7 +309,7 @@ def Matroid(groundset=None, data=None, **kwds):
             sage: M1 = Matroid(groundset='abc', circuits=['bc'])
 
         A matroid specified by a list of circuits gets converted to a
-        :class:`CircuitsMatroid <sage.matroids.basis_matroid.CircuitsMatroid>`
+        :class:`CircuitsMatroid <sage.matroids.circuits_matroid.CircuitsMatroid>`
         internally::
 
             sage: from sage.matroids.circuits_matroid import CircuitsMatroid
@@ -329,6 +333,16 @@ def Matroid(groundset=None, data=None, **kwds):
             sage: M.is_valid()
             False
 
+    #.  Dictionary of flats:
+
+        ::
+
+            sage: M = Matroid(flats={0: [''], 1: ['a', 'b'], 2: ['ab']})
+            sage: M.is_valid()
+            True
+            sage: type(M)
+            <class 'sage.matroids.flats_matroid.FlatsMatroid'>
+
     #.  Graph:
 
         Sage has great support for graphs, see :mod:`sage.graphs.graph`.
@@ -698,8 +712,9 @@ def Matroid(groundset=None, data=None, **kwds):
     key = None
     if data is None:
         for k in ['bases', 'independent_sets', 'circuits',
-                  'nonspanning_circuits', 'graph', 'matrix', 'reduced_matrix',
-                  'rank_function', 'revlex', 'circuit_closures', 'matroid']:
+                  'nonspanning_circuits', 'flats', 'graph', 'matrix',
+                  'reduced_matrix', 'rank_function', 'revlex',
+                  'circuit_closures', 'matroid']:
             if k in kwds:
                 data = kwds.pop(k)
                 key = k
@@ -791,6 +806,16 @@ def Matroid(groundset=None, data=None, **kwds):
             nsc_defined=True
         )
 
+    # Flats
+    elif key == 'flats':
+        # Determine groundset
+        if groundset is None:
+            groundset = set()
+            for i in data:
+                for F in data[i]:
+                    groundset.update(F)
+        M = FlatsMatroid(groundset=groundset, flats=data)
+
     # Graphs:
     elif key == 'graph':
         from sage.graphs.graph import Graph

src/sage/matroids/flats_matroid.pxd

@@ -0,0 +1,20 @@
+from sage.matroids.matroid cimport Matroid
+
+cdef class FlatsMatroid(Matroid):
+    cdef frozenset _groundset  # _E
+    cdef int _matroid_rank  # _R
+    cdef dict _F  # flats
+    cpdef groundset(self)
+    cpdef _rank(self, X)
+    cpdef full_rank(self)
+    cpdef _is_independent(self, F)
+
+    # enumeration
+    cpdef flats(self, k)
+    cpdef whitney_numbers2(self)
+
+    # isomorphism
+    cpdef _is_isomorphic(self, other, certificate=*)
+
+    # verification
+    cpdef is_valid(self)