Improve matroid docstrings

Up to GraphicMatroid

src/sage/matroids/advanced.py

@@ -14,6 +14,7 @@
         - :class:`MinorMatroid <sage.matroids.minor_matroid.MinorMatroid>`
         - :class:`DualMatroid <sage.matroids.dual_matroid.DualMatroid>`
         - :class:`RankMatroid <sage.matroids.rank_matroid.RankMatroid>`
+        - :class:`RankMatroid <sage.matroids.circuits_matroid.CircuitsMatroid>`
         - :class:`CircuitClosuresMatroid <sage.matroids.circuit_closures_matroid.CircuitClosuresMatroid>`
         - :class:`BasisMatroid <sage.matroids.basis_matroid.BasisMatroid>`
         - :class:`FlatsMatroid <sage.matroids.flats_matroid.FlatsMatroid>`
@@ -49,6 +50,7 @@
 
 - Stefan van Zwam (2013-04-01): initial version
 """
+
 import sage.matroids.matroid
 import sage.matroids.basis_exchange_matroid
 from .minor_matroid import MinorMatroid
@@ -63,6 +65,4 @@
 from . import lean_matrix
 from .extension import LinearSubclasses, MatroidExtensions
 from .union_matroid import MatroidUnion, MatroidSum, PartitionMatroid
-
-from sage.misc.lazy_import import lazy_import
-from sage.matroids.graphic_matroid import GraphicMatroid
+from .graphic_matroid import GraphicMatroid

src/sage/matroids/catalog.py

@@ -6,6 +6,7 @@
 :mod:`matroids.catalog <sage.matroids.catalog>` (type this and hit :kbd:`Tab`
 for a list).
 """
+
 from sage.matroids.database_matroids import (
     U24, U25, U35, K4, Whirl3, Q6, P6, U36, R6,
     Fano, FanoDual, NonFano, NonFanoDual, O7, P7,
@@ -16,6 +17,7 @@
     R12, ExtendedTernaryGolayCode, T12,
     PG23,
 )
+
 from sage.matroids.database_matroids import (
     RelaxedNonFano, TippedFree3spike,
     AG23minusDY, TQ8, P8p, KP8, Sp8, Sp8pp, LP8, WQ8,
@@ -30,6 +32,7 @@
     FA15,
     N4,
 )
+
 from sage.matroids.database_matroids import (
     NonVamos, NotP8, AG23minus,
     P9, R9A, R9B, Block_9_4, TicTacToe,

src/sage/matroids/circuit_closures_matroid.pyx

@@ -65,7 +65,6 @@ from .matroid cimport Matroid
 from .set_system cimport SetSystem
 from .utilities import setprint_s, cmp_elements_key
 
-
 cdef class CircuitClosuresMatroid(Matroid):
     r"""
     A general matroid `M` is characterized by its rank `r(M)` and the set of

src/sage/matroids/constructor.py

@@ -105,7 +105,6 @@
 #                  https://www.gnu.org/licenses/
 # ****************************************************************************
 
-
 from itertools import combinations
 from sage.matrix.constructor import Matrix
 from sage.structure.element import is_Matrix
@@ -131,7 +130,6 @@
 from .graphic_matroid import GraphicMatroid
 import sage.matroids.utilities
 
-
 def Matroid(groundset=None, data=None, **kwds):
     r"""
     Construct a matroid.

src/sage/matroids/database_collections.py

@@ -159,14 +159,14 @@ def AllMatroids(n, r=None, type="all"):
         ....:             for M in matroids.AllMatroids(n+7, r+3, "unorientable"):
         ....:                 assert M.is_valid()
     """
-    from sage.matroids.constructor import Matroid
+    from .basis_matroid import BasisMatroid
     from sage.features.databases import DatabaseMatroids
     DatabaseMatroids().require()
     import matroid_database
 
     if type != "all" and type != "unorientable":
         try:
-            getattr(Matroid(bases=[[1, 2], [1, 3]]), "is_" + type)
+            getattr(BasisMatroid(groundset=[0], bases=[[0]]), "is_" + type)
         except AttributeError:
             raise AttributeError(
                 "The type \"%s\" is not available. " % type +
@@ -184,7 +184,7 @@ def AllMatroids(n, r=None, type="all"):
 
     for r in rng:
         if (r == 0 or r == n) and type != "unorientable":
-            M = Matroid(groundset=range(n), bases=[range(r)])
+            M = BasisMatroid(groundset=range(n), bases=[range(r)])
             M.rename(type + "_n" + str(n).zfill(2) + "_r" + str(r).zfill(2) + "_#" + "0" + ": " + repr(M))
             if type == "all":
                 yield M
@@ -207,7 +207,7 @@ def AllMatroids(n, r=None, type="all"):
 
             cnt = 0
             for B in matroids_bases(n, rp):
-                M = Matroid(groundset=range(n), bases=B)
+                M = BasisMatroid(groundset=range(n), bases=B)
 
                 if type != "unorientable" and n - r < r:
                     M = M.dual()

src/sage/matroids/dual_matroid.py

@@ -112,9 +112,7 @@ def groundset(self):
 
         The groundset is the set of elements that comprise the matroid.
 
-        OUTPUT:
-
-        A set.
+        OUTPUT: set
 
         EXAMPLES::
 
@@ -133,11 +131,9 @@ def _rank(self, X):
 
         INPUT:
 
-        - ``X`` -- an object with Python's ``frozenset`` interface.
+        - ``X`` -- an object with Python's ``frozenset`` interface
 
-        OUTPUT:
-
-        The rank of ``X`` in the matroid.
+        OUTPUT: integer
 
         EXAMPLES::
 
@@ -153,12 +149,10 @@ def _corank(self, X):
 
         INPUT:
 
-        - ``X`` -- An object with Python's ``frozenset`` interface
-          containing a subset of ``self.groundset()``.
-
-        OUTPUT:
+        - ``X`` -- an object with Python's ``frozenset`` interface
+          containing a subset of ``self.groundset()``
 
-        The corank of ``X``.
+        OUTPUT: integer
 
         EXAMPLES::
 
@@ -177,9 +171,7 @@ def _max_independent(self, X):
         - ``X`` -- an object with Python's ``frozenset`` interface containing
           a subset of ``self.groundset()``
 
-        OUTPUT:
-
-        A maximal independent subset of ``X``.
+        OUTPUT: a maximal independent subset of ``X``
 
         EXAMPLES::
 
@@ -204,10 +196,8 @@ def _circuit(self, X):
         - ``X`` -- an object with Python's ``frozenset`` interface containing
           a subset of ``self.groundset()``
 
-        OUTPUT:
-
-        A circuit contained in ``X``, if it exists. Otherwise an error is
-        raised.
+        OUTPUT: a circuit contained in ``X``, if it exists; otherwise, an error is
+        raised
 
         EXAMPLES::
 
@@ -232,9 +222,7 @@ def _closure(self, X):
         - ``X`` -- an object with Python's ``frozenset`` interface containing
           a subset of ``self.groundset()``
 
-        OUTPUT:
-
-        The smallest closed set containing ``X``.
+        OUTPUT: the smallest closed set containing ``X``
 
         EXAMPLES::
 
@@ -253,9 +241,7 @@ def _max_coindependent(self, X):
         - ``X`` -- an object with Python's ``frozenset`` interface containing
           a subset of ``self.groundset()``
 
-        OUTPUT:
-
-        A maximal coindependent subset of ``X``.
+        OUTPUT: a maximal coindependent subset of ``X``
 
         EXAMPLES::
 
@@ -280,9 +266,7 @@ def _coclosure(self, X):
         - ``X`` -- an object with Python's ``frozenset`` interface containing
           a subset of ``self.groundset()``
 
-        OUTPUT:
-
-        The smallest coclosed set containing ``X``.
+        OUTPUT: the smallest coclosed set containing ``X``
 
         EXAMPLES::
 
@@ -301,10 +285,8 @@ def _cocircuit(self, X):
         - ``X`` -- an object with Python's ``frozenset`` interface containing
           a subset of ``self.groundset()``
 
-        OUTPUT:
-
-        A cocircuit contained in ``X``, if it exists. Otherwise an error is
-        raised.
+        OUTPUT: a cocircuit contained in ``X``, if it exists; otherwise, an error is
+        raised
 
         EXAMPLES::
 
@@ -324,23 +306,21 @@ def _minor(self, contractions=None, deletions=None):
 
         INPUT:
 
-        - ``contractions`` -- An object with Python's ``frozenset`` interface
-          containing a subset of ``self.groundset()``.
-        - ``deletions`` -- An object with Python's ``frozenset`` interface
-          containing a subset of ``self.groundset()``.
-
-        OUTPUT:
+        - ``contractions`` -- an object with Python's ``frozenset`` interface
+          containing a subset of ``self.groundset()``
+        - ``deletions`` -- an object with Python's ``frozenset`` interface
+          containing a subset of ``self.groundset()``
 
-        A ``DualMatroid`` instance representing
+        OUTPUT: a class:`DualMatroid` representing
         `(``self._matroid`` / ``deletions`` \ ``contractions``)^*`
 
         .. NOTE::
 
             This method does NOT do any checks. Besides the assumptions above,
             we assume the following:
 
-            - ``contractions`` is independent
-            - ``deletions`` is coindependent
+            - ``contractions`` is independent;
+            - ``deletions`` is coindependent;
             - ``contractions`` and ``deletions`` are disjoint.
 
         EXAMPLES::
@@ -367,8 +347,7 @@ def dual(self):
         Let `M` be a matroid with groundset `E`. If `B` is the set of bases
         of `M`, then the set `\{E - b : b \in B\}` is the set of bases of
         another matroid, the *dual* of `M`. Note that the dual of the dual of
-        `M` equals `M`, so if this is the
-        :class:`DualMatroid` instance
+        `M` equals `M`, so if this is the :class:`DualMatroid` instance
         wrapping `M` then the returned matroid is `M`.
 
         OUTPUT: the dual matroid
@@ -521,17 +500,18 @@ def __reduce__(self):
         version = 0
         return sage.matroids.unpickling.unpickle_dual_matroid, (version, data)
 
-    def relabel(self, f):
+    def relabel(self, mapping):
         r"""
         Return an isomorphic matroid with relabeled groundset.
 
-        The output is obtained by relabeling each element ``e`` by ``f[e]``,
-        where ``f`` is a given injective map. If ``e not in f`` then the
-        identity map is assumed.
+        The output is obtained by relabeling each element ``e`` by
+        ``mapping[e]``, where ``mapping`` is a given injective map. If
+        ``e not in mapping`` then the identity map is assumed.
 
         INPUT:
 
-        - ``f`` -- a python object such that `f[e]` is the new label of `e`
+        - ``mapping`` -- a python object such that `mapping[e]` is the new
+          label of `e`
 
         OUTPUT: matroid
 
@@ -554,5 +534,5 @@ def relabel(self, f):
             sage: for S in powerset(M.groundset()):
             ....:     assert M.rank(S) == N.rank([f[x] for x in S])
         """
-        M = self._matroid.relabel(f).dual()
+        M = self._matroid.relabel(mapping).dual()
         return M

src/sage/matroids/extension.pyx

@@ -15,10 +15,8 @@ See also :mod:`sage.matroids.advanced`.
 AUTHORS:
 
 - Rudi Pendavingh, Stefan van Zwam (2013-04-01): initial version
-
-Methods
-=======
 """
+
 # ****************************************************************************
 #       Copyright (C) 2013 Rudi Pendavingh <[email protected]>
 #       Copyright (C) 2013 Stefan van Zwam <[email protected]>
@@ -33,7 +31,6 @@ Methods
 from sage.data_structures.bitset_base cimport *
 from sage.matroids.basis_matroid cimport BasisMatroid
 
-
 cdef class CutNode:
     """
     An internal class used for creating linear subclasses of a matroids in a
@@ -246,7 +243,6 @@ cdef class LinearSubclassesIter:
                 if res is not None:
                     return res
 
-
 cdef class LinearSubclasses:
     r"""
     An iterable set of linear subclasses of a matroid.
@@ -410,7 +406,6 @@ cdef class LinearSubclasses:
         cdef long p
         return [self._hyperplanes[p] for p in node.planes()]
 
-
 cdef class MatroidExtensions(LinearSubclasses):
     r"""
     An iterable set of single-element extensions of a given matroid.

src/sage/matroids/flats_matroid.pyx

@@ -19,6 +19,7 @@ AUTHORS:
 
 - Giorgos Mousa (2024-01-01): initial version
 """
+
 # ****************************************************************************
 #       Copyright (C) 2024 Giorgos Mousa <[email protected]>
 #
@@ -28,11 +29,11 @@ AUTHORS:
 # (at your option) any later version.
 #                  https://www.gnu.org/licenses/
 # ****************************************************************************
+
 from cpython.object cimport Py_EQ, Py_NE
 from sage.structure.richcmp cimport rich_to_bool, richcmp
 from .matroid cimport Matroid
 from .set_system cimport SetSystem
-from .utilities import setprint_s
 
 cdef class FlatsMatroid(Matroid):
     r"""