combin · Poset¶

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

Worked example¶

The complete checked program Reduce a finite Poset and its order complex with replayable evidence uses this API directly.

# SPDX-License-Identifier: MIT
# Copyright (c) 2026 Benjamin Antieau and Deven Manam
"""Reduce a finite Poset and its order complex with replayable evidence."""

from noether import Z
from noether.combin import Poset


def main() -> None:
    chain = Poset(4, [(0, 1), (1, 2), (2, 3)])
    core = chain.core()
    core.verify(chain)
    assert core.core.order == 1

    order_complex = chain.order_complex()
    morse = order_complex.morse_reduction(Z)
    morse.verify()
    assert sum(morse.critical_cells) == 1
    assert morse.reduced.homology_invariants(0).free_rank == 1
    print(
        f"Poset order {chain.order} -> core order {core.core.order}; "
        f"Morse cells {morse.original_cells} -> {morse.critical_cells}"
    )


if __name__ == "__main__":
    main()

Run it with .venv/bin/python examples/32_poset_core_and_morse.py.

`combin.Poset`¶

The thin Python handle around Noether's validated Rust [Poset].

Detailed contract

The thin Python handle around Noether's validated Rust [Poset].

Construction accepts strict generating relations on 0..n_elements. Redundant transitive relations and duplicates are removed, so covers is always the directed Hasse graph. Python stores no parallel order relation or caller-supplied claims about lattice or graded structure.

from noether.combin import Poset

diamond = Poset(4, [(0, 1), (0, 2), (1, 3), (2, 3)])
assert diamond.leq(0, 3)
assert diamond.covers.edge_count == 4

PythonRust

Poset(n_elements: int, relations: Sequence[Sequence[int]])

noether::combin::Poset · Direct Rust declaration

pub struct Poset { /* 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/Poset@1

Executable usage: examples/32_poset_core_and_morse.py:10 · examples/32_poset_core_and_morse.py:21 · examples/32_poset_core_and_morse.py:3 · examples/32_poset_core_and_morse.py:6 · validation/unit/combin/test_acceptance_workload.py:15 · validation/unit/combin/test_acceptance_workload.py:24

Example

from noether.combin import Poset
diamond = Poset(4, [(0, 1), (0, 2), (1, 3), (2, 3)])
assert diamond.leq(0, 3)
assert diamond.covers.edge_count == 4

`combin.Poset.eq`¶

Test mathematical equality with another value.

PythonRust

(self, other: object) -> bool

noether::combin::Poset · 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/Poset@1

`combin.Poset.automorphism_group`¶

Compute the exact automorphism group on the element ids.

Detailed contract

Compute the exact automorphism group acting on the element ids.

PythonRust

(self) -> PermutationGroup

noether::combin::Poset::automorphism_group · Direct Rust declaration

pub fn automorphism_group(&self) -> Result<PermutationGroup, PosetError>

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/Poset@1

Executable usage: examples/21_graph_symmetry.py:16 · examples/21_graph_symmetry.py:18 · examples/29_integral_line_configurations.py:10 · validation/unit/category/test_category.py:55 · validation/unit/combin/test_acceptance_workload.py:31 · validation/unit/combin/test_graph_facade.py:91

`combin.Poset.beat_points`¶

Current up- and down-beat-point certificates.

Detailed contract

All current up- and down-beat certificates in deterministic order.

PythonRust

(self) -> list[BeatPoint]

noether::combin::Poset::beat_points · Direct Rust declaration

pub fn beat_points(&self) -> Vec<BeatPoint>

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/Poset@1

Executable usage: validation/unit/combinatorics/test_poset.py:92 · validation/unit/combinatorics/test_poset.py:94 · validation/unit/combinatorics/test_poset.py:95

`combin.Poset.canonical_form`¶

Return the representative minimizing the principal-downset tuple.

Detailed contract

Return the exact representative minimizing the principal-downset tuple. Isomorphic finite posets have equal canonical forms. Canonicalization is explicit: it does not change labeled equality or faithful serialization.

PythonRust

(self) -> Poset

noether::combin::Poset::canonical_form · Direct Rust declaration

pub fn canonical_form(&self) -> Result<Self, PosetError>

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/Poset@1

Executable usage: validation/unit/category/test_category.py:38 · validation/unit/combin/test_acceptance_workload.py:27 · validation/unit/combin/test_acceptance_workload.py:29 · validation/unit/infra/test_discovery.py:122 · validation/unit/infra/test_discovery.py:125 · validation/unit/infra/test_discovery.py:56

Example

from noether.combin import Poset
poset = Poset(3, [(2, 1), (1, 0)])
result = poset.canonical_form()
assert result.to_json() == '{"order":3,"covers":[[0,1],[1,2]]}'

`combin.Poset.canonical_label`¶

Compute the exact labeling minimizing the principal-downset tuple.

Detailed contract

Compute the exact principal-downset canonical labeling. For a labeling by 0..order, associate to element k the integer sum(2^j) over every j <= k in the poset. The canonical form is the relabeling whose sequence of these integers is lexicographically least. The returned permutation maps the current element ids to those canonical ids; its automorphism group acts on the current ids.

PythonRust

(self) -> PosetCanonicalLabel

noether::combin::Poset::canonical_label · Direct Rust declaration

pub fn canonical_label(&self) -> Result<PosetCanonicalLabel, PosetError>

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/Poset@1

Executable usage: examples/21_graph_symmetry.py:14 · validation/unit/category/test_category.py:16 · validation/unit/category/test_category.py:17 · validation/unit/combin/test_graph_facade.py:84 · validation/unit/combin/test_graph_facade.py:85 · validation/unit/combinatorics/test_poset.py:106

`combin.Poset.comparable_pair_count`¶

Number of strict comparable pairs.

PythonRust

(self) -> int

noether::combin::Poset::comparable_pair_count · Direct Rust declaration

pub fn comparable_pair_count(&self) -> usize

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/Poset@1

Executable usage: validation/unit/combinatorics/test_poset.py:81 · validation/corpus/combin/integer-poset-invariants.py:30

`combin.Poset.connected_components`¶

Weakly connected components of the Hasse diagram.

PythonRust

(self) -> list[list[VertexId]]

noether::combin::Poset::connected_components · Direct Rust declaration

pub fn connected_components(&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/Poset@1

Executable usage: validation/unit/combin/test_graph_facade.py:32 · validation/unit/combinatorics/test_poset.py:82 · validation/parity/combinatorics/test_tree_core_parity.py:258 · validation/parity/u1_graph_core.py:310 · validation/parity/u1_graph_core.py:43 · validation/backends/graph/igraph_oracle.py:10

`combin.Poset.core`¶

Delete beat points and return replayable reduction evidence.

Detailed contract

Delete beat points deterministically and return replayable core evidence.

PythonRust

(self) -> CoreReduction

noether::combin::Poset::core · Direct Rust declaration

pub fn core(&self) -> Result<CoreReduction, PosetError>

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/Poset@1

Executable usage: examples/32_poset_core_and_morse.py:11 · examples/32_poset_core_and_morse.py:12 · examples/32_poset_core_and_morse.py:13 · examples/32_poset_core_and_morse.py:21 · validation/unit/combinatorics/test_poset.py:101 · validation/unit/combinatorics/test_poset.py:104

`combin.Poset.covers`¶

The directed Hasse diagram as the public graph type.

Detailed contract

The directed Hasse diagram, with every cover edge oriented upward.

PythonRust

(self) -> Graph

noether::combin::Poset::covers · Direct Rust declaration

pub fn covers(&self) -> &Graph

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/Poset@1

Executable usage: validation/unit/combin/test_acceptance_workload.py:30 · validation/unit/combinatorics/test_poset.py:24 · validation/unit/combinatorics/test_poset.py:25 · validation/unit/combinatorics/test_poset.py:26 · validation/unit/combinatorics/test_poset.py:43 · validation/unit/combinatorics/test_poset.py:46

`combin.Poset.from_json`¶

Deserialize and revalidate a finite poset.

PythonRust

(value: str) -> Poset

noether::combin::Poset · 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/Poset@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.Poset.graded_homology_invariants`¶

Compute lean integral homology after beat-point reduction.

Detailed contract

Compute lean integral homology after deterministic beat-point reduction. This is the poset-specific homology playbook: reducible posets first pass to their canonical core, while core posets proceed directly to the sparse Smith-normal-form calculation. The returned vector is indexed by homological degree and carries no source-retaining boundary witnesses.

PythonRust

(self) -> list[FinitelyGeneratedAbelianGroup]

noether::combin::Poset::graded_homology_invariants · Direct Rust declaration

pub fn graded_homology_invariants( &self, ) -> Result<Vec<FinitelyGeneratedAbelianGroup>, PosetError>

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/Poset@1

Executable usage: validation/unit/combinatorics/test_poset.py:107 · validation/unit/combinatorics/test_poset.py:108 · validation/unit/homalg/test_chain_complex.py:162 · validation/unit/homalg/test_chain_complex.py:179 · validation/unit/homalg/test_padic_homology_facade.py:106 · validation/unit/homalg/test_padic_homology_facade.py:202

`combin.Poset.height`¶

Number of elements in a longest chain.

Detailed contract

Number of elements in a longest chain; zero for the empty poset.

PythonRust

(self) -> int

noether::combin::Poset::height · Direct Rust declaration

pub fn height(&self) -> usize

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/Poset@1

Executable usage: validation/unit/category/test_category.py:72 · validation/unit/combinatorics/test_poset.py:83 · validation/bench/macaulay2_core.py:358 · validation/corpus/combin/integer-poset-invariants.py:26 · validation/corpus/combin/integer-poset-invariants.py:36 · validation/corpus/combin/weak-order-tamari-posets.py:31

`combin.Poset.is_core`¶

Whether this poset has no beat points.

Detailed contract

Whether the poset has no beat points.

PythonRust

(self) -> bool

noether::combin::Poset::is_core · Direct Rust declaration

pub fn is_core(&self) -> bool

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/Poset@1

Executable usage: validation/unit/combinatorics/test_poset.py:105

`combin.Poset.is_lattice`¶

Whether every pair has a meet and a join.

Detailed contract

Whether every pair has a unique meet and join.

PythonRust

(self) -> bool

noether::combin::Poset::is_lattice · Direct Rust declaration

pub fn is_lattice(&self) -> bool

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/Poset@1

Executable usage: validation/unit/combinatorics/test_poset.py:85 · validation/unit/infra/test_discovery.py:193 · validation/corpus/combin/integer-poset-invariants.py:33 · validation/corpus/combin/weak-order-tamari-posets.py:30

`combin.Poset.is_self_dual`¶

Whether this poset is isomorphic to its opposite.

PythonRust

(self) -> bool

noether::combin::Poset::is_self_dual · Direct Rust declaration

pub fn is_self_dual(&self) -> Result<bool, PosetError>

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/Poset@1

Executable usage: validation/unit/combinatorics/test_poset.py:86 · validation/unit/infra/test_discovery.py:194 · validation/corpus/combin/integer-poset-invariants.py:34

`combin.Poset.leq`¶

Return whether lower <= upper.

Detailed contract

Return whether lower <= upper.

PythonRust

(self, lower: VertexId, upper: VertexId) -> bool

noether::combin::Poset::leq · Direct Rust declaration

pub fn leq(&self, lower: VertexId, upper: VertexId) -> Result<bool, PosetError>

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/Poset@1

Executable usage: validation/unit/combinatorics/test_boundary.py:22 · validation/unit/combinatorics/test_boundary.py:23 · validation/unit/combinatorics/test_partition_types.py:64 · validation/unit/combinatorics/test_poset.py:149 · validation/unit/combinatorics/test_poset.py:27 · validation/unit/combinatorics/test_poset.py:28

`combin.Poset.maximal_elements`¶

Maximal elements in ascending id order.

PythonRust

(self) -> list[VertexId]

noether::combin::Poset::maximal_elements · Direct Rust declaration

pub fn maximal_elements(&self) -> 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/Poset@1

Executable usage: validation/unit/combinatorics/test_poset.py:80 · validation/corpus/combin/integer-poset-invariants.py:29

`combin.Poset.minimal_elements`¶

Minimal elements in ascending id order.

PythonRust

(self) -> list[VertexId]

noether::combin::Poset::minimal_elements · Direct Rust declaration

pub fn minimal_elements(&self) -> 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/Poset@1

Executable usage: validation/unit/combinatorics/test_poset.py:79 · validation/corpus/combin/integer-poset-invariants.py:28

`combin.Poset.opposite`¶

Reverse every comparison while retaining element ids.

Detailed contract

Reverse every comparison while retaining the current element ids.

PythonRust

(self) -> Poset

noether::combin::Poset::opposite · Direct Rust declaration

pub fn opposite(&self) -> Result<Self, PosetError>

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/Poset@1

Executable usage: validation/unit/combinatorics/test_poset.py:87 · validation/parity/linalg/test_lattice_enumeration_parity.py:7

`combin.Poset.order`¶

Number of elements.

PythonRust

(self) -> int

noether::combin::Poset::order · Direct Rust declaration

pub fn order(&self) -> usize

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/Poset@1

Executable usage: examples/11_qadic_witt_vectors.py:14 · examples/12_number_field_ideals.py:13 · examples/12_number_field_ideals.py:14 · examples/12_number_field_ideals.py:17 · examples/15_groebner_twisted_cubic.py:18 · examples/19_permutation_groups.py:13

`combin.Poset.order_complex`¶

Construct the order complex, preserving poset element ids.

Detailed contract

Construct the order complex from its maximal chains. Vertex ids are retained. Deterministic limits bound both maximal-chain enumeration and the downward closure materialized by the existing simplicial-complex representation.

PythonRust

(self) -> SimplicialComplex

noether::combin::Poset::order_complex · Direct Rust declaration

pub fn order_complex(&self) -> Result<SimplicialComplex, PosetError>

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/Poset@1

Executable usage: examples/32_poset_core_and_morse.py:15 · examples/32_poset_core_and_morse.py:16 · validation/unit/combinatorics/test_poset.py:112 · validation/unit/combinatorics/test_poset.py:129 · validation/unit/infra/test_discovery.py:196

`combin.Poset.strict_lower_counts`¶

Strict predecessor counts indexed by element id.

Detailed contract

Number of strict predecessors of every element, indexed by element id.

PythonRust

(self) -> list[int]

noether::combin::Poset::strict_lower_counts · Direct Rust declaration

pub fn strict_lower_counts(&self) -> Vec<usize>

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/Poset@1

Executable usage: validation/unit/combinatorics/test_poset.py:77 · validation/corpus/combin/integer-poset-invariants.py:31

`combin.Poset.strict_upper_counts`¶

Strict successor counts indexed by element id.

Detailed contract

Number of strict successors of every element, indexed by element id.

PythonRust

(self) -> list[int]

noether::combin::Poset::strict_upper_counts · Direct Rust declaration

pub fn strict_upper_counts(&self) -> Vec<usize>

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/Poset@1

Executable usage: validation/unit/combinatorics/test_poset.py:78 · validation/corpus/combin/integer-poset-invariants.py:32

`combin.Poset.to_json`¶

Serialize only the validated defining Hasse diagram.

PythonRust

(self) -> str

noether::combin::Poset · 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/Poset@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.Poset.width`¶

Maximum antichain size.

Detailed contract

Maximum size of an antichain, via the exact Dilworth matching reduction.

PythonRust

(self) -> int

noether::combin::Poset::width · Direct Rust declaration

pub fn width(&self) -> usize

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/Poset@1

Executable usage: validation/unit/category/test_category.py:81 · validation/unit/combinatorics/test_poset.py:84 · validation/unit/infra/test_discovery.py:192 · validation/corpus/combin/integer-poset-invariants.py:27 · validation/corpus/combin/integer-poset-invariants.py:36 · validation/corpus/combin/weak-order-tamari-posets.py:31

combin · Poset¶

Worked example¶

combin.Poset¶

combin.Poset.__eq__¶

combin.Poset.automorphism_group¶

combin.Poset.beat_points¶

combin.Poset.canonical_form¶

combin.Poset.canonical_label¶

combin.Poset.comparable_pair_count¶

combin.Poset.connected_components¶

combin.Poset.core¶

combin.Poset.covers¶

combin.Poset.from_json¶

combin.Poset.graded_homology_invariants¶

combin.Poset.height¶

combin.Poset.is_core¶

combin.Poset.is_lattice¶

combin.Poset.is_self_dual¶

combin.Poset.leq¶

combin.Poset.maximal_elements¶

combin.Poset.minimal_elements¶

combin.Poset.opposite¶

combin.Poset.order¶

combin.Poset.order_complex¶

combin.Poset.strict_lower_counts¶

combin.Poset.strict_upper_counts¶

combin.Poset.to_json¶

combin.Poset.width¶

`combin.Poset`¶

`combin.Poset.eq`¶

`combin.Poset.automorphism_group`¶

`combin.Poset.beat_points`¶

`combin.Poset.canonical_form`¶

`combin.Poset.canonical_label`¶

`combin.Poset.comparable_pair_count`¶

`combin.Poset.connected_components`¶

`combin.Poset.core`¶

`combin.Poset.covers`¶

`combin.Poset.from_json`¶

`combin.Poset.graded_homology_invariants`¶

`combin.Poset.height`¶

`combin.Poset.is_core`¶

`combin.Poset.is_lattice`¶

`combin.Poset.is_self_dual`¶

`combin.Poset.leq`¶

`combin.Poset.maximal_elements`¶

`combin.Poset.minimal_elements`¶

`combin.Poset.opposite`¶

`combin.Poset.order`¶

`combin.Poset.order_complex`¶

`combin.Poset.strict_lower_counts`¶

`combin.Poset.strict_upper_counts`¶

`combin.Poset.to_json`¶

`combin.Poset.width`¶