Skip to content

combin · Matroid

12 accepted declarations. Python and Rust forms, contracts, evidence, failure boundaries, and checked usages are kept together below.

Worked example

The complete checked program Compute the Tutte polynomial of the uniform matroid U(2, 3) uses this API directly.

# SPDX-License-Identifier: MIT
# Copyright (c) 2026 Benjamin Antieau and Deven Manam
"""Compute the Tutte polynomial of the uniform matroid U(2, 3)."""

from noether.combin import Matroid


def main() -> None:
    matroid = Matroid.from_bases([0, 1, 2], [[0, 1], [0, 2], [1, 2]])
    tutte = matroid.tutte_polynomial()
    assert tutte.coefficient([2, 0]) == 1
    assert tutte.coefficient([1, 0]) == 1
    assert tutte.coefficient([0, 1]) == 1
    print(f"T_U(2,3)(x,y) = {tutte}")


if __name__ == "__main__":
    main()

Run it with .venv/bin/python examples/22_matroids_and_tutte.py.

combin.Matroid

A thin Python handle around Noether's validated Rust [Matroid].

class Matroid

noether::combin::Matroid · Direct Rust declaration

pub struct Matroid { /* private fields */ }
Contract Value
Guarantee checked deterministic result
Determinism deterministic
Availability default CPU build
Domain implementation crates noether, graph-core, perm-core
GIL attached / bounded
Semantic ID noether/combin/Matroid@1

Executable usage: examples/22_matroids_and_tutte.py:5 · examples/22_matroids_and_tutte.py:9 · validation/unit/combin/test_acceptance_workload.py:13 · validation/unit/combin/test_acceptance_workload.py:69 · validation/unit/combin/test_acceptance_workload.py:86 · validation/unit/combinatorics/test_boundary.py:10

combin.Matroid.__eq__

Test mathematical equality with another value.

(self, other: object) -> bool

noether::combin::Matroid · Python projection

Python projection convenience over this Rust mathematical type
Contract Value
Guarantee checked deterministic result
Determinism deterministic
Availability default CPU build
Domain implementation crates noether, graph-core, perm-core
GIL attached / bounded
Semantic ID noether/combin/Matroid@1

combin.Matroid.bases

Complete canonical basis family.

Detailed contract

Canonical family of bases in lexicographic element order.

(self) -> tuple[frozenset[VertexId], ...]

noether::combin::Matroid::bases · Direct Rust declaration

pub fn bases(&self) -> Vec<Vec<VertexId>>
Contract Value
Guarantee checked deterministic result
Determinism deterministic
Availability default CPU build
Domain implementation crates noether, graph-core, perm-core
GIL attached / bounded
Semantic ID noether/combin/Matroid@1

Executable usage: validation/unit/combin/test_acceptance_workload.py:76 · validation/unit/combin/test_acceptance_workload.py:77 · validation/unit/combinatorics/test_matroid.py:31 · validation/unit/combinatorics/test_matroid.py:57 · validation/unit/combinatorics/test_matroid.py:59 · validation/unit/combinatorics/test_matroid.py:76

combin.Matroid.circuits

Minimal dependent subsets.

Detailed contract

Minimal dependent subsets, in deterministic order.

(self) -> tuple[frozenset[VertexId], ...]

noether::combin::Matroid::circuits · Direct Rust declaration

pub fn circuits(&self) -> Vec<Vec<VertexId>>
Contract Value
Guarantee checked deterministic result
Determinism deterministic
Availability default CPU build
Domain implementation crates noether, graph-core, perm-core
GIL attached / bounded
Semantic ID noether/combin/Matroid@1

Executable usage: validation/unit/combin/test_acceptance_workload.py:75 · validation/unit/combinatorics/test_matroid.py:37 · validation/unit/combinatorics/test_matroid.py:77 · validation/parity/combinatorics/test_matroid_parity.py:66 · validation/parity/combinatorics/test_matroid_parity.py:83 · validation/corpus/combin/basic-matroid-cryptomorphisms.py:15

combin.Matroid.contract

Contract one element while preserving the remaining labels.

Detailed contract

Contract one labeled element while preserving every remaining label.

(self, element: VertexId) -> Matroid

noether::combin::Matroid::contract · Direct Rust declaration

pub fn contract(&self, element: VertexId) -> Result<Self, MatroidError>
Contract Value
Guarantee checked deterministic result
Determinism deterministic
Availability default CPU build
Domain implementation crates noether, graph-core, perm-core
GIL attached / bounded
Semantic ID noether/combin/Matroid@1

Executable usage: examples/40_exterior_algebra.py:29 · validation/unit/combin/test_acceptance_workload.py:77 · validation/unit/combinatorics/test_matroid.py:55 · validation/unit/homalg/test_exterior_algebra.py:129 · validation/unit/homalg/test_exterior_algebra.py:130 · validation/unit/homalg/test_exterior_algebra.py:131

combin.Matroid.delete

Delete one element while preserving the remaining labels.

Detailed contract

Delete one labeled element while preserving every remaining label.

(self, element: VertexId) -> Matroid

noether::combin::Matroid::delete · Direct Rust declaration

pub fn delete(&self, element: VertexId) -> Result<Self, MatroidError>
Contract Value
Guarantee checked deterministic result
Determinism deterministic
Availability default CPU build
Domain implementation crates noether, graph-core, perm-core
GIL attached / bounded
Semantic ID noether/combin/Matroid@1

Executable usage: validation/unit/combin/test_acceptance_workload.py:76 · validation/unit/combinatorics/test_matroid.py:54 · validation/unit/combinatorics/test_matroid.py:86 · validation/parity/combinatorics/test_matroid_parity.py:68 · validation/parity/combinatorics/test_matroid_parity.py:89 · validation/corpus/combin/basic-matroid-cryptomorphisms.py:17

combin.Matroid.from_bases

Construct from a labeled ground set and the complete basis family.

Detailed contract

Construct and validate a matroid from its complete family of bases.

(ground_set: Sequence[VertexId], bases: Sequence[Sequence[VertexId]]) -> Matroid

noether::combin::Matroid::from_bases · Direct Rust declaration

pub fn from_bases( ground_set: Vec<VertexId>, bases: Vec<Vec<VertexId>>, ) -> Result<Self, MatroidError>
Contract Value
Guarantee checked deterministic result
Determinism deterministic
Availability default CPU build
Domain implementation crates noether, graph-core, perm-core
GIL attached / bounded
Semantic ID noether/combin/Matroid@1

Executable usage: examples/22_matroids_and_tutte.py:9 · validation/unit/combin/test_acceptance_workload.py:69 · validation/unit/combinatorics/test_boundary.py:35 · validation/unit/combinatorics/test_boundary.py:43 · validation/unit/combinatorics/test_boundary.py:46 · validation/unit/combinatorics/test_boundary.py:49

combin.Matroid.from_json

Deserialize and revalidate every matroid axiom.

(value: str) -> Matroid

noether::combin::Matroid · Python projection

Python projection convenience over this Rust mathematical type
Contract Value
Guarantee checked deterministic result
Determinism deterministic
Availability default CPU build
Domain implementation crates noether, graph-core, perm-core
GIL attached / bounded
Semantic ID noether/combin/Matroid@1

Executable usage: validation/unit/category/test_category.py:14 · validation/unit/combin/test_acceptance_workload.py:65 · validation/unit/combin/test_acceptance_workload.py:86 · validation/unit/combin/test_graph_facade.py:106 · validation/unit/combin/test_graph_facade.py:25 · validation/unit/combinatorics/test_kashiwara_crystal.py:32

combin.Matroid.ground_set

Canonical ordered element identifiers.

Detailed contract

Canonical ordered ground set.

(self) -> list[VertexId]

noether::combin::Matroid::ground_set · Direct Rust declaration

pub fn ground_set(&self) -> &[VertexId] ⓘ
Contract Value
Guarantee checked deterministic result
Determinism deterministic
Availability default CPU build
Domain implementation crates noether, graph-core, perm-core
GIL attached / bounded
Semantic ID noether/combin/Matroid@1

Executable usage: validation/unit/combinatorics/test_matroid.py:29 · validation/unit/combinatorics/test_matroid.py:30 · validation/unit/combinatorics/test_matroid.py:56 · validation/unit/combinatorics/test_matroid.py:58 · validation/unit/combinatorics/test_matroid.py:75 · validation/unit/combinatorics/test_matroid.py:90

combin.Matroid.rank

Rank of a subset of the ground set.

Detailed contract

Rank of one subset of the ground set.

(self, subset: Sequence[VertexId]) -> int

noether::combin::Matroid::rank · Direct Rust declaration

pub fn rank(&self, subset: &[VertexId]) -> Result<usize, MatroidError>
Contract Value
Guarantee checked deterministic result
Determinism deterministic
Availability default CPU build
Domain implementation crates noether, graph-core, perm-core
GIL attached / bounded
Semantic ID noether/combin/Matroid@1

Executable usage: examples/38_exact_linear_systems.py:78 · examples/distributed/f2_linear_algebra.py:34 · examples/distributed/f2_linear_algebra.py:54 · examples/distributed/f2_linear_algebra.py:55 · examples/distributed/f2_linear_algebra.py:60 · validation/unit/combin/test_acceptance_workload.py:74

combin.Matroid.to_json

Serialize only the canonical ground set and complete basis family.

(self) -> str

noether::combin::Matroid · Python projection

Python projection convenience over this Rust mathematical type
Contract Value
Guarantee checked deterministic result
Determinism deterministic
Availability default CPU build
Domain implementation crates noether, graph-core, perm-core
GIL attached / bounded
Semantic ID noether/combin/Matroid@1

Executable usage: validation/unit/category/test_category.py:14 · validation/unit/category/test_category.py:15 · validation/unit/combin/test_acceptance_workload.py:30 · validation/unit/combin/test_acceptance_workload.py:65 · validation/unit/combin/test_acceptance_workload.py:86 · validation/unit/combin/test_graph_facade.py:106

combin.Matroid.tutte_polynomial

Exact Tutte polynomial in Z[x, y].

Detailed contract

Exact Tutte polynomial in the canonical context Z[x, y].

(self) -> Polynomial[IntegerRing]

noether::combin::Matroid::tutte_polynomial · Direct Rust declaration

pub fn tutte_polynomial(&self) -> Result<Polynomial<IntegerRing>, MatroidError>
Contract Value
Guarantee checked deterministic result
Determinism deterministic
Availability default CPU build
Domain implementation crates noether, graph-core, perm-core
GIL released
Semantic ID noether/combin/Matroid@1

Executable usage: examples/22_matroids_and_tutte.py:10 · validation/unit/combin/test_acceptance_workload.py:81 · validation/unit/combinatorics/test_boundary.py:43 · validation/unit/combinatorics/test_boundary.py:46 · validation/unit/combinatorics/test_boundary.py:49 · validation/unit/combinatorics/test_matroid.py:63