sagemathgh-38057: matroids: Declare function input and return types

    
Especially for internal functions (starting with `_`).

The PR includes many changes, most of which are algorithmically
inconsequential (simple type declarations and docstring edits).

Careful review is mostly needed for commit `f0fd595`, where some extra
type castings are done within basic `matroid` functions.

### ⌛ Dependencies

- Depends on sagemath#38056.
    
URL: sagemath#38057
Reported by: gmou3
Reviewer(s): gmou3, Matthias Köppe, Travis Scrimshaw

src/sage/algebras/orlik_solomon.py

@@ -73,7 +73,9 @@ class OrlikSolomonAlgebra(CombinatorialFreeModule):
         14
         sage: G = OS.algebra_generators()
         sage: M.broken_circuits()
-        frozenset({frozenset({1, 2, 3})})
+        SetSystem of 1 sets over 4 elements
+        sage: M.broken_circuits()[0]
+        frozenset({1, 2, 3})
         sage: G[1] * G[2] * G[3]
         OS{0, 1, 2} - OS{0, 1, 3} + OS{0, 2, 3}
 

src/sage/geometry/hyperplane_arrangement/arrangement.py

@@ -1955,7 +1955,7 @@ def skip(b_list):
         lhs = matrix(R, d, d)
         rhs = vector(R, d)
         vertices = set()
-        for indices in M.independent_r_sets(d):
+        for indices in M.independent_sets(d):
             for row, i in enumerate(indices):
                 lhs[row] = A_list[i]
             b_list = [b_list_list[i] for i in indices]

src/sage/matroids/advanced.py

@@ -1,5 +1,5 @@
 r"""
-Advanced matroid functionality.
+Advanced matroid functionality
 
 This module collects a number of advanced functions which are not directly
 available to the end user by default. To import them into the main namespace,
@@ -10,26 +10,28 @@
 This adds the following to the main namespace:
 
     - Matroid classes:
-        - :class:`MinorMatroid <sage.matroids.minor_matroid.MinorMatroid>`
-        - :class:`DualMatroid <sage.matroids.dual_matroid.DualMatroid>`
-        - :class:`RankMatroid <sage.matroids.rank_matroid.RankMatroid>`
+
+        - :class:`BasisMatroid <sage.matroids.basis_matroid.BasisMatroid>`
         - :class:`CircuitsMatroid <sage.matroids.circuits_matroid.CircuitsMatroid>`
         - :class:`CircuitClosuresMatroid <sage.matroids.circuit_closures_matroid.CircuitClosuresMatroid>`
-        - :class:`BasisMatroid <sage.matroids.basis_matroid.BasisMatroid>`
+        - :class:`DualMatroid <sage.matroids.dual_matroid.DualMatroid>`
         - :class:`FlatsMatroid <sage.matroids.flats_matroid.FlatsMatroid>`
+        - :class:`GraphicMatroid <sage.matroids.graphic_matroid.GraphicMatroid>`
         - :class:`LinearMatroid <sage.matroids.linear_matroid.LinearMatroid>`
         - :class:`RegularMatroid <sage.matroids.linear_matroid.RegularMatroid>`
         - :class:`BinaryMatroid <sage.matroids.linear_matroid.BinaryMatroid>`
         - :class:`TernaryMatroid <sage.matroids.linear_matroid.TernaryMatroid>`
         - :class:`QuaternaryMatroid <sage.matroids.linear_matroid.QuaternaryMatroid>`
-        - :class:`GraphicMatroid <sage.matroids.linear_matroid.GraphicMatroid>`
+        - :class:`MinorMatroid <sage.matroids.minor_matroid.MinorMatroid>`
+        - :class:`RankMatroid <sage.matroids.rank_matroid.RankMatroid>`
 
     Note that you can construct all of these through the
     :func:`Matroid() <sage.matroids.constructor.Matroid>` function, which is
     available on startup. Using the classes directly can sometimes be useful
     for faster code (e.g. if your code calls ``Matroid()`` frequently).
 
     - Other classes:
+
         - :class:`LinearSubclasses <sage.matroids.extension.LinearSubclasses>`
         - :class:`MatroidExtensions <sage.matroids.extension.MatroidExtensions>`
 
@@ -39,30 +41,34 @@
     :meth:`Matroid.extensions() <sage.matroids.matroid.Matroid.extensions>`.
 
     - Useful functions:
+
         - :func:`setprint() <sage.matroids.utilities.setprint>`
         - :func:`newlabel() <sage.matroids.utilities.newlabel>`
         - :func:`get_nonisomorphic_matroids() <sage.matroids.utilities.get_nonisomorphic_matroids>`
-        - :func:`lift_cross_ratios() <sage.matroids.linear_matroid.lift_cross_ratios>`
-        - :func:`lift_map() <sage.matroids.linear_matroid.lift_map>`
+        - :func:`lift_cross_ratios() <sage.matroids.utilities.lift_cross_ratios>`
+        - :func:`lift_map() <sage.matroids.utilities.lift_map>`
+        - :func:`cmp_elements_key() <sage.matroids.utilities.cmp_elements_key>`
 
 AUTHORS:
 
 - Stefan van Zwam (2013-04-01): initial version
 """
-import sage.matroids.matroid
-import sage.matroids.basis_exchange_matroid
-from .minor_matroid import MinorMatroid
-from .dual_matroid import DualMatroid
-from .rank_matroid import RankMatroid
-from .circuits_matroid import CircuitsMatroid
-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
-from .extension import LinearSubclasses, MatroidExtensions
-from .union_matroid import MatroidUnion, MatroidSum, PartitionMatroid
 
+from sage.matroids import matroid, basis_exchange_matroid, lean_matrix
+
+from sage.matroids.basis_matroid import BasisMatroid
+from sage.matroids.circuits_matroid import CircuitsMatroid
+from sage.matroids.circuit_closures_matroid import CircuitClosuresMatroid
+from sage.matroids.dual_matroid import DualMatroid
+from sage.matroids.flats_matroid import FlatsMatroid
+from sage.matroids.linear_matroid import LinearMatroid, RegularMatroid, BinaryMatroid, TernaryMatroid, QuaternaryMatroid
+from sage.matroids.minor_matroid import MinorMatroid
+from sage.matroids.rank_matroid import RankMatroid
+from sage.matroids.union_matroid import MatroidUnion, MatroidSum, PartitionMatroid
+
+# lazy import of GraphicMatroid for modularization purposes
 from sage.misc.lazy_import import lazy_import
 lazy_import('sage.matroids.graphic_matroid', 'GraphicMatroid')
+
+from sage.matroids.extension import LinearSubclasses, MatroidExtensions
+from sage.matroids.utilities import setprint, newlabel, get_nonisomorphic_matroids, lift_cross_ratios, lift_map, cmp_elements_key

src/sage/matroids/all.py

@@ -6,8 +6,6 @@
 install_doc(__package__, __doc__)
 
 from sage.misc.lazy_import import lazy_import
-# from constructor import Matroid
-# import matroids_catalog as matroids
 lazy_import('sage.matroids.constructor', 'Matroid')
 lazy_import('sage.matroids', 'matroids_catalog', 'matroids')
 del lazy_import

src/sage/matroids/basis_exchange_matroid.pxd

@@ -1,6 +1,5 @@
 from sage.data_structures.bitset cimport *
 from sage.data_structures.bitset_base cimport bitset_t, bitset_s
-
 from sage.matroids.matroid cimport Matroid
 from sage.matroids.set_system cimport SetSystem
 
@@ -38,47 +37,43 @@ cdef class BasisExchangeMatroid(Matroid):
 
     cdef bint _set_current_basis(self, F) noexcept
 
-    cpdef groundset(self)
-    cpdef groundset_list(self)
+    cpdef frozenset groundset(self)
+    cpdef list groundset_list(self)
     cpdef full_rank(self)
     cpdef full_corank(self)
 
     cpdef basis(self)
     cpdef _move_current_basis(self, X, Y)
 
-    cpdef _max_independent(self, F)
-    cpdef _rank(self, F)
-    cpdef _circuit(self, F)
-    cpdef _fundamental_circuit(self, B, e)
-    cpdef _closure(self, F)
+    cpdef frozenset _max_independent(self, frozenset F)
+    cpdef int _rank(self, frozenset F)
+    cpdef frozenset _circuit(self, frozenset F)
+    cpdef frozenset _fundamental_circuit(self, frozenset B, e)
+    cpdef frozenset _closure(self, frozenset F)
 
-    cpdef _max_coindependent(self, F)
-    cpdef _corank(self, F)
-    cpdef _cocircuit(self, F)
-    cpdef _fundamental_cocircuit(self, B, e)
-    cpdef _coclosure(self, F)
+    cpdef frozenset _max_coindependent(self, frozenset F)
+    cpdef int _corank(self, frozenset F)
+    cpdef frozenset _cocircuit(self, frozenset F)
+    cpdef frozenset _fundamental_cocircuit(self, frozenset B, e)
+    cpdef frozenset _coclosure(self, frozenset F)
 
-    cpdef _augment(self, X, Y)
-    cpdef _is_independent(self, F)
+    cpdef frozenset _augment(self, frozenset X, frozenset Y)
+    cpdef bint _is_independent(self, frozenset F)
 
-    cpdef whitney_numbers2(self)
+    cpdef list whitney_numbers2(self)
     cdef  _whitney_numbers2_rec(self, object f_vec, bitset_t* flats, bitset_t* todo, long elt, long rnk)
-    cpdef flats(self, R)
     cdef  _flats_rec(self, SetSystem Rflats, long R, bitset_t* flats, bitset_t* todo, long elt, long rnk)
-    cpdef coflats(self, R)
     cdef  _coflats_rec(self, SetSystem Rcoflats, long R, bitset_t* coflats, bitset_t* todo, long elt, long cornk)
     cdef _flat_element_inv(self, long k)
     cdef  _flat_element_inv_rec(self, object f_inc, long R, bitset_t* flats, bitset_t* todo, long elt, long i)
 
     cpdef bases_count(self)
-    cpdef independent_r_sets(self, long r)
-    cpdef bases(self)
-    cpdef dependent_r_sets(self, long r)
-    cpdef nonbases(self)
+    cpdef SetSystem independent_sets(self, long k=*)
+    cpdef SetSystem dependent_sets(self, long k)
 
-    cpdef nonspanning_circuits(self)
-    cpdef cocircuits(self)
-    cpdef circuits(self)
+    cpdef SetSystem nonspanning_circuits(self)
+    cpdef SetSystem cocircuits(self)
+    cpdef SetSystem circuits(self, k=*)
 
     cpdef _characteristic_setsystem(self)
     cpdef _weak_invariant(self)
@@ -95,6 +90,6 @@ cdef class BasisExchangeMatroid(Matroid):
     cpdef _is_isomorphism(self, other, morphism)
     cdef bint __is_isomorphism(self, BasisExchangeMatroid other, morphism) noexcept
 
-    cpdef is_valid(self)
+    cpdef bint is_valid(self)
 
 cdef bint nxksrd(bitset_s *b, long n, long k, bint succ) noexcept