Circuits matroids¶
Matroids are characterized by a list of circuits, which are minimal dependent
sets. The CircuitsMatroid class implements matroids using this information
as data.
A CircuitsMatroid can be created from another matroid or from a list of
circuits. For a full description of allowed inputs, see
below. It is
recommended to use the Matroid()
function for a more flexible way of constructing a CircuitsMatroid and
other classes of matroids. For direct access to the CircuitsMatroid
constructor, run:
sage: from sage.matroids.circuits_matroid import CircuitsMatroid
>>> from sage.all import *
>>> from sage.matroids.circuits_matroid import CircuitsMatroid
AUTHORS:
- Giorgos Mousa (2023-12-23): initial version 
- class sage.matroids.circuits_matroid.CircuitsMatroid[source]¶
- Bases: - Matroid- A matroid defined by its circuits. - INPUT: - M– matroid (default:- None)
- groundset– list (default:- None); the groundset of the matroid
- circuits– list (default:- None); the collection of circuits of the matroid
- nsc_defined– boolean (default:- False); whether the matroid was defined by its nonspanning circuits
 - Note - For a more flexible means of input, use the - Matroid()function.- bases_iterator()[source]¶
- Return an iterator over the bases of the matroid. - EXAMPLES: - sage: from sage.matroids.circuits_matroid import CircuitsMatroid sage: M = CircuitsMatroid(matroids.Uniform(2, 4)) sage: it = M.bases_iterator() sage: it.__next__() frozenset({0, 1}) sage: sorted(M.bases_iterator(), key=str) [frozenset({0, 1}), frozenset({0, 2}), frozenset({0, 3}), frozenset({1, 2}), frozenset({1, 3}), frozenset({2, 3})] - >>> from sage.all import * >>> from sage.matroids.circuits_matroid import CircuitsMatroid >>> M = CircuitsMatroid(matroids.Uniform(Integer(2), Integer(4))) >>> it = M.bases_iterator() >>> it.__next__() frozenset({0, 1}) >>> sorted(M.bases_iterator(), key=str) [frozenset({0, 1}), frozenset({0, 2}), frozenset({0, 3}), frozenset({1, 2}), frozenset({1, 3}), frozenset({2, 3})] 
 - broken_circuit_complex(ordering=None, reduced=False)[source]¶
- Return the broken circuit complex of - self.- The broken circuit complex of a matroid with a total ordering \(<\) on the groundset is obtained from the - NBC setsunder subset inclusion.- INPUT: - ordering– list (optional); a total ordering of the groundset
- reduced– boolean (default:- False); whether to return the reduced broken circuit complex (the link at the smallest element)
 - OUTPUT: a simplicial complex of the NBC sets under inclusion - EXAMPLES: - sage: M = Matroid(circuits=[[1, 2, 3], [3, 4, 5], [1, 2, 4, 5]]) sage: M.broken_circuit_complex() Simplicial complex with vertex set (1, 2, 3, 4, 5) and facets {(1, 2, 4), (1, 2, 5), (1, 3, 4), (1, 3, 5)} sage: M.broken_circuit_complex([5, 4, 3, 2, 1]) Simplicial complex with vertex set (1, 2, 3, 4, 5) and facets {(1, 3, 5), (1, 4, 5), (2, 3, 5), (2, 4, 5)} sage: M.broken_circuit_complex([5, 4, 3, 2, 1], reduced=True) Simplicial complex with vertex set (1, 2, 3, 4) and facets {(1, 3), (1, 4), (2, 3), (2, 4)} - >>> from sage.all import * >>> M = Matroid(circuits=[[Integer(1), Integer(2), Integer(3)], [Integer(3), Integer(4), Integer(5)], [Integer(1), Integer(2), Integer(4), Integer(5)]]) >>> M.broken_circuit_complex() Simplicial complex with vertex set (1, 2, 3, 4, 5) and facets {(1, 2, 4), (1, 2, 5), (1, 3, 4), (1, 3, 5)} >>> M.broken_circuit_complex([Integer(5), Integer(4), Integer(3), Integer(2), Integer(1)]) Simplicial complex with vertex set (1, 2, 3, 4, 5) and facets {(1, 3, 5), (1, 4, 5), (2, 3, 5), (2, 4, 5)} >>> M.broken_circuit_complex([Integer(5), Integer(4), Integer(3), Integer(2), Integer(1)], reduced=True) Simplicial complex with vertex set (1, 2, 3, 4) and facets {(1, 3), (1, 4), (2, 3), (2, 4)} - For a matroid with loops, the broken circuit complex is not defined, and the method yields an error: - sage: M = Matroid(groundset=[0, 1, 2], circuits=[[0]]) sage: M.broken_circuit_complex() Traceback (most recent call last): ... ValueError: broken circuit complex of matroid with loops is not defined - >>> from sage.all import * >>> M = Matroid(groundset=[Integer(0), Integer(1), Integer(2)], circuits=[[Integer(0)]]) >>> M.broken_circuit_complex() Traceback (most recent call last): ... ValueError: broken circuit complex of matroid with loops is not defined 
 - circuits(k=None)[source]¶
- Return the circuits of the matroid. - INPUT: - k– integer (optional); the length of the circuits
 - OUTPUT: - SetSystem- EXAMPLES: - sage: from sage.matroids.circuits_matroid import CircuitsMatroid sage: M = CircuitsMatroid(matroids.Uniform(2, 4)) sage: M.circuits() SetSystem of 4 sets over 4 elements sage: list(M.circuits(0)) [] sage: sorted(M.circuits(3), key=str) [frozenset({0, 1, 2}), frozenset({0, 1, 3}), frozenset({0, 2, 3}), frozenset({1, 2, 3})] - >>> from sage.all import * >>> from sage.matroids.circuits_matroid import CircuitsMatroid >>> M = CircuitsMatroid(matroids.Uniform(Integer(2), Integer(4))) >>> M.circuits() SetSystem of 4 sets over 4 elements >>> list(M.circuits(Integer(0))) [] >>> sorted(M.circuits(Integer(3)), key=str) [frozenset({0, 1, 2}), frozenset({0, 1, 3}), frozenset({0, 2, 3}), frozenset({1, 2, 3})] 
 - circuits_iterator(k=None)[source]¶
- Return an iterator over the circuits of the matroid. - INPUT: - k– integer (optional); the length of the circuits
 - EXAMPLES: - sage: from sage.matroids.circuits_matroid import CircuitsMatroid sage: M = CircuitsMatroid(matroids.Uniform(2, 4)) sage: sum(1 for C in M.circuits_iterator()) 4 sage: list(M.circuits_iterator(0)) [] sage: sorted(M.circuits_iterator(3), key=str) [frozenset({0, 1, 2}), frozenset({0, 1, 3}), frozenset({0, 2, 3}), frozenset({1, 2, 3})] - >>> from sage.all import * >>> from sage.matroids.circuits_matroid import CircuitsMatroid >>> M = CircuitsMatroid(matroids.Uniform(Integer(2), Integer(4))) >>> sum(Integer(1) for C in M.circuits_iterator()) 4 >>> list(M.circuits_iterator(Integer(0))) [] >>> sorted(M.circuits_iterator(Integer(3)), key=str) [frozenset({0, 1, 2}), frozenset({0, 1, 3}), frozenset({0, 2, 3}), frozenset({1, 2, 3})] 
 - dependent_sets(k)[source]¶
- Return the dependent sets of fixed size. - INPUT: - k– integer
 - OUTPUT: - SetSystem- EXAMPLES: - sage: from sage.matroids.circuits_matroid import CircuitsMatroid sage: M = CircuitsMatroid(matroids.catalog.Vamos()) sage: M.dependent_sets(3) SetSystem of 0 sets over 8 elements sage: sorted([sorted(X) for X in M.dependent_sets(4)]) [['a', 'b', 'c', 'd'], ['a', 'b', 'e', 'f'], ['a', 'b', 'g', 'h'], ['c', 'd', 'e', 'f'], ['e', 'f', 'g', 'h']] - >>> from sage.all import * >>> from sage.matroids.circuits_matroid import CircuitsMatroid >>> M = CircuitsMatroid(matroids.catalog.Vamos()) >>> M.dependent_sets(Integer(3)) SetSystem of 0 sets over 8 elements >>> sorted([sorted(X) for X in M.dependent_sets(Integer(4))]) [['a', 'b', 'c', 'd'], ['a', 'b', 'e', 'f'], ['a', 'b', 'g', 'h'], ['c', 'd', 'e', 'f'], ['e', 'f', 'g', 'h']] 
 - full_rank()[source]¶
- Return the rank of the matroid. - The rank of the matroid is the size of the largest independent subset of the groundset. - OUTPUT: integer - EXAMPLES: - sage: M = matroids.Theta(20) sage: M.full_rank() 20 - >>> from sage.all import * >>> M = matroids.Theta(Integer(20)) >>> M.full_rank() 20 
 - girth()[source]¶
- Return the girth of the matroid. - The girth is the size of the smallest circuit. In case the matroid has no circuits the girth is \(\infty\). - EXAMPLES: - sage: matroids.Theta(10).girth() 3 - >>> from sage.all import * >>> matroids.Theta(Integer(10)).girth() 3 - REFERENCES: - [Oxl2011], p. 327. 
 - groundset()[source]¶
- Return the groundset of the matroid. - The groundset is the set of elements that comprise the matroid. - OUTPUT: set - EXAMPLES: - sage: M = matroids.Theta(2) sage: sorted(M.groundset()) ['x0', 'x1', 'y0', 'y1'] - >>> from sage.all import * >>> M = matroids.Theta(Integer(2)) >>> sorted(M.groundset()) ['x0', 'x1', 'y0', 'y1'] 
 - independent_sets(k=-1)[source]¶
- Return the independent sets of the matroid. - INPUT: - k– integer (optional); if specified, return the size-\(k\) independent sets of the matroid
 - OUTPUT: - SetSystem- EXAMPLES: - sage: from sage.matroids.circuits_matroid import CircuitsMatroid sage: M = CircuitsMatroid(matroids.catalog.Pappus()) sage: M.independent_sets(4) SetSystem of 0 sets over 9 elements sage: M.independent_sets(3) SetSystem of 75 sets over 9 elements sage: frozenset({'a', 'c', 'e'}) in _ True - >>> from sage.all import * >>> from sage.matroids.circuits_matroid import CircuitsMatroid >>> M = CircuitsMatroid(matroids.catalog.Pappus()) >>> M.independent_sets(Integer(4)) SetSystem of 0 sets over 9 elements >>> M.independent_sets(Integer(3)) SetSystem of 75 sets over 9 elements >>> frozenset({'a', 'c', 'e'}) in _ True - See also - M.bases()
 - is_paving()[source]¶
- Return if - selfis paving.- A matroid is paving if each of its circuits has size \(r\) or \(r+1\). - OUTPUT: boolean - EXAMPLES: - sage: from sage.matroids.circuits_matroid import CircuitsMatroid sage: M = CircuitsMatroid(matroids.catalog.Vamos()) sage: M.is_paving() True - >>> from sage.all import * >>> from sage.matroids.circuits_matroid import CircuitsMatroid >>> M = CircuitsMatroid(matroids.catalog.Vamos()) >>> M.is_paving() True 
 - is_valid(certificate=False)[source]¶
- Test if - selfobeys the matroid axioms.- For a matroid defined by its circuits, we check the circuit axioms. - INPUT: - certificate– boolean (default:- False)
 - OUTPUT: boolean, or (boolean, dictionary) - EXAMPLES: - sage: C = [[1, 2, 3], [3, 4, 5], [1, 2, 4, 5]] sage: M = Matroid(circuits=C) sage: M.is_valid() True sage: C = [[1, 2], [1, 2, 3], [3, 4, 5], [1, 2, 4, 5]] sage: M = Matroid(circuits=C) sage: M.is_valid() False sage: C = [[3, 6], [1, 2, 3], [3, 4, 5], [1, 2, 4, 5]] sage: M = Matroid(circuits=C) sage: M.is_valid() False sage: C = [[3, 6], [1, 2, 3], [3, 4, 5], [1, 2, 6], [6, 4, 5], [1, 2, 4, 5]] sage: M = Matroid(circuits=C) sage: M.is_valid() True sage: C = [[], [1, 2, 3], [3, 4, 5], [1, 2, 4, 5]] sage: M = Matroid(circuits=C) sage: M.is_valid() False sage: C = [[1, 2, 3], [3, 4, 5]] sage: M = Matroid(circuits=C) sage: M.is_valid(certificate=True) (False, {'circuit 1': frozenset({...}), 'circuit 2': frozenset({...}), 'element': 3, 'error': 'elimination axiom failed'}) - >>> from sage.all import * >>> C = [[Integer(1), Integer(2), Integer(3)], [Integer(3), Integer(4), Integer(5)], [Integer(1), Integer(2), Integer(4), Integer(5)]] >>> M = Matroid(circuits=C) >>> M.is_valid() True >>> C = [[Integer(1), Integer(2)], [Integer(1), Integer(2), Integer(3)], [Integer(3), Integer(4), Integer(5)], [Integer(1), Integer(2), Integer(4), Integer(5)]] >>> M = Matroid(circuits=C) >>> M.is_valid() False >>> C = [[Integer(3), Integer(6)], [Integer(1), Integer(2), Integer(3)], [Integer(3), Integer(4), Integer(5)], [Integer(1), Integer(2), Integer(4), Integer(5)]] >>> M = Matroid(circuits=C) >>> M.is_valid() False >>> C = [[Integer(3), Integer(6)], [Integer(1), Integer(2), Integer(3)], [Integer(3), Integer(4), Integer(5)], [Integer(1), Integer(2), Integer(6)], [Integer(6), Integer(4), Integer(5)], [Integer(1), Integer(2), Integer(4), Integer(5)]] >>> M = Matroid(circuits=C) >>> M.is_valid() True >>> C = [[], [Integer(1), Integer(2), Integer(3)], [Integer(3), Integer(4), Integer(5)], [Integer(1), Integer(2), Integer(4), Integer(5)]] >>> M = Matroid(circuits=C) >>> M.is_valid() False >>> C = [[Integer(1), Integer(2), Integer(3)], [Integer(3), Integer(4), Integer(5)]] >>> M = Matroid(circuits=C) >>> M.is_valid(certificate=True) (False, {'circuit 1': frozenset({...}), 'circuit 2': frozenset({...}), 'element': 3, 'error': 'elimination axiom failed'}) 
 - no_broken_circuits_facets(ordering=None, reduced=False)[source]¶
- Return the no broken circuits (NBC) facets of - self.- INPUT: - ordering– list (optional); a total ordering of the groundset
- reduced– boolean (default:- False)
 - OUTPUT: - SetSystem- EXAMPLES: - sage: M = Matroid(circuits=[[0, 1, 2]]) sage: M.no_broken_circuits_facets(ordering=[1, 0, 2]) SetSystem of 2 sets over 3 elements sage: sorted([sorted(X) for X in _]) [[0, 1], [1, 2]] sage: M.no_broken_circuits_facets(ordering=[1, 0, 2], reduced=True) SetSystem of 2 sets over 3 elements sage: sorted([sorted(X) for X in _]) [[0], [2]] - >>> from sage.all import * >>> M = Matroid(circuits=[[Integer(0), Integer(1), Integer(2)]]) >>> M.no_broken_circuits_facets(ordering=[Integer(1), Integer(0), Integer(2)]) SetSystem of 2 sets over 3 elements >>> sorted([sorted(X) for X in _]) [[0, 1], [1, 2]] >>> M.no_broken_circuits_facets(ordering=[Integer(1), Integer(0), Integer(2)], reduced=True) SetSystem of 2 sets over 3 elements >>> sorted([sorted(X) for X in _]) [[0], [2]] 
 - no_broken_circuits_sets(ordering=None, reduced=False)[source]¶
- Return the no broken circuits (NBC) sets of - self.- An NBC set is a subset \(A\) of the groundset under some total ordering \(<\) such that \(A\) contains no broken circuit. - INPUT: - ordering– list (optional); a total ordering of the groundset
- reduced– boolean (default:- False)
 - OUTPUT: - SetSystem- EXAMPLES: - sage: M = Matroid(circuits=[[1, 2, 3], [3, 4, 5], [1, 2, 4, 5]]) sage: SimplicialComplex(M.no_broken_circuits_sets()) Simplicial complex with vertex set (1, 2, 3, 4, 5) and facets {(1, 2, 4), (1, 2, 5), (1, 3, 4), (1, 3, 5)} sage: SimplicialComplex(M.no_broken_circuits_sets([5, 4, 3, 2, 1])) Simplicial complex with vertex set (1, 2, 3, 4, 5) and facets {(1, 3, 5), (1, 4, 5), (2, 3, 5), (2, 4, 5)} - >>> from sage.all import * >>> M = Matroid(circuits=[[Integer(1), Integer(2), Integer(3)], [Integer(3), Integer(4), Integer(5)], [Integer(1), Integer(2), Integer(4), Integer(5)]]) >>> SimplicialComplex(M.no_broken_circuits_sets()) Simplicial complex with vertex set (1, 2, 3, 4, 5) and facets {(1, 2, 4), (1, 2, 5), (1, 3, 4), (1, 3, 5)} >>> SimplicialComplex(M.no_broken_circuits_sets([Integer(5), Integer(4), Integer(3), Integer(2), Integer(1)])) Simplicial complex with vertex set (1, 2, 3, 4, 5) and facets {(1, 3, 5), (1, 4, 5), (2, 3, 5), (2, 4, 5)} - sage: M = Matroid(circuits=[[1, 2, 3], [1, 4, 5], [2, 3, 4, 5]]) sage: SimplicialComplex(M.no_broken_circuits_sets([5, 4, 3, 2, 1])) Simplicial complex with vertex set (1, 2, 3, 4, 5) and facets {(1, 3, 5), (2, 3, 5), (2, 4, 5), (3, 4, 5)} - >>> from sage.all import * >>> M = Matroid(circuits=[[Integer(1), Integer(2), Integer(3)], [Integer(1), Integer(4), Integer(5)], [Integer(2), Integer(3), Integer(4), Integer(5)]]) >>> SimplicialComplex(M.no_broken_circuits_sets([Integer(5), Integer(4), Integer(3), Integer(2), Integer(1)])) Simplicial complex with vertex set (1, 2, 3, 4, 5) and facets {(1, 3, 5), (2, 3, 5), (2, 4, 5), (3, 4, 5)} 
 - nonspanning_circuits()[source]¶
- Return the nonspanning circuits of the matroid. - OUTPUT: - SetSystem- EXAMPLES: - sage: from sage.matroids.circuits_matroid import CircuitsMatroid sage: M = CircuitsMatroid(matroids.Uniform(2, 4)) sage: M.nonspanning_circuits() SetSystem of 0 sets over 4 elements sage: M = matroids.Theta(5) sage: M.nonspanning_circuits() SetSystem of 15 sets over 10 elements - >>> from sage.all import * >>> from sage.matroids.circuits_matroid import CircuitsMatroid >>> M = CircuitsMatroid(matroids.Uniform(Integer(2), Integer(4))) >>> M.nonspanning_circuits() SetSystem of 0 sets over 4 elements >>> M = matroids.Theta(Integer(5)) >>> M.nonspanning_circuits() SetSystem of 15 sets over 10 elements 
 - nonspanning_circuits_iterator()[source]¶
- Return an iterator over the nonspanning circuits of the matroid. - EXAMPLES: - sage: from sage.matroids.circuits_matroid import CircuitsMatroid sage: M = CircuitsMatroid(matroids.Uniform(2, 4)) sage: list(M.nonspanning_circuits_iterator()) [] - >>> from sage.all import * >>> from sage.matroids.circuits_matroid import CircuitsMatroid >>> M = CircuitsMatroid(matroids.Uniform(Integer(2), Integer(4))) >>> list(M.nonspanning_circuits_iterator()) [] 
 - relabel(mapping)[source]¶
- Return an isomorphic matroid with relabeled groundset. - The output is obtained by relabeling each element \(e\) by - mapping[e], where- mappingis a given injective map. If- mapping[e]is not defined, then the identity map is assumed.- INPUT: - mapping– a Python object such that- mapping[e]is the new label of \(e\)
 - OUTPUT: matroid - EXAMPLES: - sage: from sage.matroids.circuits_matroid import CircuitsMatroid sage: M = CircuitsMatroid(matroids.catalog.RelaxedNonFano()) sage: sorted(M.groundset()) [0, 1, 2, 3, 4, 5, 6] sage: N = M.relabel({'g': 'x', 0: 'z'}) # 'g': 'x' is ignored sage: from sage.matroids.utilities import cmp_elements_key sage: sorted(N.groundset(), key=cmp_elements_key) [1, 2, 3, 4, 5, 6, 'z'] sage: M.is_isomorphic(N) True - >>> from sage.all import * >>> from sage.matroids.circuits_matroid import CircuitsMatroid >>> M = CircuitsMatroid(matroids.catalog.RelaxedNonFano()) >>> sorted(M.groundset()) [0, 1, 2, 3, 4, 5, 6] >>> N = M.relabel({'g': 'x', Integer(0): 'z'}) # 'g': 'x' is ignored >>> from sage.matroids.utilities import cmp_elements_key >>> sorted(N.groundset(), key=cmp_elements_key) [1, 2, 3, 4, 5, 6, 'z'] >>> M.is_isomorphic(N) True