Skip to content

combin · Tree

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

Worked example

The complete checked program Use the fixed-precision Witt ring W(F_9) uses this API directly.

# SPDX-License-Identifier: MIT
# Copyright (c) 2026 Benjamin Antieau and Deven Manam
"""Use the fixed-precision Witt ring W(F_9)."""

from noether.numthy import FiniteField, QadicRing


def main() -> None:
    residue_field = FiniteField.extension(3, 2)
    witt_ring = QadicRing(residue_field, absolute_precision=4)
    residue = residue_field.generator() + residue_field.one()
    lift = witt_ring.teichmuller(residue)
    assert witt_ring.residue(lift) == residue
    assert lift**residue_field.order == lift
    print(f"Teichmuller({residue}) = {lift}")


if __name__ == "__main__":
    main()

Run it with .venv/bin/python examples/11_qadic_witt_vectors.py.

combin.Tree

A rooted tree over graph-core's CSR graph.

Detailed contract

A rooted tree over graph-core's CSR graph.

Built from n vertices + an edge list (validated acyclic + connected) and rooted at a chosen vertex. Precomputes the structures backing O(1) LCA (Euler tour + sparse table), binary-lifting kth_ancestor, and the preorder subtree intervals.

Serialization delegates to the kernel value's validated (order, edges, root) representation. Its LCA and decomposition structures are derived and never reach the wire.

class Tree

noether::combin::Tree · Direct Rust declaration

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

Executable usage: validation/unit/combin/test_graph_facade.py:100 · validation/unit/combin/test_graph_facade.py:106 · validation/unit/combin/test_graph_facade.py:112 · validation/unit/combin/test_graph_facade.py:116 · validation/unit/combin/test_graph_facade.py:13 · validation/unit/combin/test_graph_facade.py:98

combin.Tree.__eq__

Test mathematical equality with another value.

(self, other: object) -> bool

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

combin.Tree.center

The graph-theoretic center: the one or two middle vertices of a diameter path, in ascending order.

Detailed contract

The graph-theoretic center: the one or two middle vertices of a diameter path, in ascending order.

The one or two vertices minimizing maximum distance to all vertices. These are the middle vertices of any diameter path. This is the graph theoretic center, not the size-balanced centroid.

(self) -> list[VertexId]

noether::combin::Tree::center · Direct Rust declaration

pub fn center(&self) -> SmallVec2
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/Tree@1

Executable usage: validation/unit/combin/test_graph_facade.py:102 · validation/unit/commalg/test_acceptance_workload.py:104 · validation/unit/commalg/test_acceptance_workload.py:112 · validation/unit/commalg/test_acceptance_workload.py:96 · validation/unit/commalg/test_acceptance_workload.py:98 · validation/unit/commalg/test_scheme_facade.py:223

combin.Tree.centroid

The tree's centroid(s) as a list[int] (ascending) — the size-balance definition: a vertex whose removal leaves no component with more than ⌊n/2⌋ vertices.

Detailed contract

The tree's centroid(s) as a list[int] (ascending) — the size-balance definition: a vertex whose removal leaves no component with more than ⌊n/2⌋ vertices. A tree has one or two centroids.

The tree’s centroid(s) — the size-balance definition: a vertex whose removal leaves no component with more than ⌊n/2⌋ vertices. A tree has one or two centroids (two iff n is even and they are adjacent). Not Sage’s center (the eccentricity-minimising centre) — a distinct notion; the parity harness pins the size-balance definition.

(self) -> list[VertexId]

noether::combin::Tree::centroid · Direct Rust declaration

pub fn centroid(&self) -> SmallVec2
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/Tree@1

Executable usage: validation/parity/combinatorics/test_tree_core_parity.py:203 · validation/parity/combinatorics/test_tree_core_parity.py:25 · validation/parity/combinatorics/test_tree_core_parity.py:271 · validation/parity/combinatorics/test_tree_core_parity.py:308 · validation/parity/combinatorics/test_tree_core_parity.py:314 · validation/parity/combinatorics/test_tree_pyo3.py:19

combin.Tree.centroid_decomposition

The recursive centroid decomposition as a dict: {"root": int, "parent": list[int | None]}, where parent[v] is v's parent in the centroid tree (None for the decomposition root).

Detailed contract

The recursive centroid decomposition as a dict: {"root": int, "parent": list[int | None]}, where parent[v] is v's parent in the centroid tree (None for the decomposition root). The decomposition has depth O(log n).

The recursive centroid decomposition as a [CentroidTree]: the centroid-decomposition parent of every vertex (the root has no parent). Each level halves the component size, so the decomposition has depth O(log n). Deep-safe: the recursion over components uses an explicit work stack.

(self) -> dict[str, Any]

noether::combin::Tree::centroid_decomposition · Direct Rust declaration

pub fn centroid_decomposition(&self) -> CentroidTree
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/Tree@1

Executable usage: validation/parity/combinatorics/test_tree_core_parity.py:28 · validation/parity/combinatorics/test_tree_pyo3.py:19 · validation/parity/combinatorics/test_tree_pyo3.py:246

combin.Tree.depth

v's depth — edges from the root to v (the root has depth 0).

Detailed contract

v's depth — edges from the root to v (the root has depth 0). Raises IndexError if v >= order.

v’s depth — edges from the root to v (the root has depth 0).

(self, vertex: VertexId) -> int

noether::combin::Tree::depth · Direct Rust declaration

pub fn depth(&self, v: u32) -> 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/Tree@1

Executable usage: validation/unit/homalg/test_module_facade.py:505 · validation/parity/combinatorics/test_tree_core_parity.py:17 · validation/parity/combinatorics/test_tree_core_parity.py:189 · validation/parity/combinatorics/test_tree_core_parity.py:194 · validation/parity/combinatorics/test_tree_core_parity.py:210 · validation/parity/combinatorics/test_tree_core_parity.py:265

combin.Tree.diameter

The tree's diameter — (length, path) where length is the number of edges on a longest path and path is a realizing vertex sequence.

Detailed contract

The tree's diameter — (length, path) where length is the number of edges on a longest path and path is a realizing vertex sequence. Works on the unrooted tree (double-BFS).

The tree’s diameter: the number of edges on a longest path, with a realizing path (a sequence of vertices). Works on the unrooted tree. Double-BFS: the farthest vertex a from any start, then the farthest b from a; a‥b is a diameter. Returns (length, path) with the path running a → … → b.

(self) -> tuple[int, list[VertexId]]

noether::combin::Tree::diameter · Direct Rust declaration

pub fn diameter(&self) -> (usize, Vec<u32>)
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/Tree@1

Executable usage: validation/unit/combin/test_graph_facade.py:103 · validation/parity/combinatorics/test_tree_core_parity.py:193 · validation/parity/combinatorics/test_tree_core_parity.py:24 · validation/parity/combinatorics/test_tree_core_parity.py:292 · validation/parity/combinatorics/test_tree_core_parity.py:319 · validation/parity/combinatorics/test_tree_core_parity.py:322

combin.Tree.distance

The tree distance between u and v — depth(u) + depth(v) − 2·depth(lca(u, v)).

Detailed contract

The tree distance between u and v — depth(u) + depth(v) − 2·depth(lca(u, v)). Raises IndexError if u or v >= order.

The tree distance between u and v — depth(u) + depth(v) − 2·depth(lca).

(self, left: VertexId, right: VertexId) -> int

noether::combin::Tree::distance · Direct Rust declaration

pub fn distance(&self, u: u32, v: u32) -> 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/Tree@1

Executable usage: validation/unit/combin/test_graph_facade.py:105 · validation/unit/combin/test_graph_facade.py:48 · validation/unit/geometry/test_geometry_facade.py:25 · validation/unit/geometry/test_geometry_facade.py:48 · validation/unit/topology/test_filtration_builders.py:100 · validation/unit/topology/test_filtration_builders.py:112

combin.Tree.edges

The defining edges as unordered [u, v] pairs.

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

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

Executable usage: validation/unit/combin/test_graph_facade.py:101 · validation/unit/infra/test_magma_release_protocol.py:256 · validation/unit/infra/test_magma_release_protocol.py:258 · validation/parity/combinatorics/test_crystals_parity.py:82 · validation/parity/combinatorics/test_crystals_parity.py:88 · validation/parity/combinatorics/test_tree_core_parity.py:119

combin.Tree.from_edges

Build a rooted tree from n vertices and an edge list.

Detailed contract

Build a rooted tree from n vertices and an edge list.

edges is a list of unordered (u, v) pairs (the tree is undirected); root selects the root (default vertex 0). Validates the acyclic + connected invariant.

Raises ValueError if the input is not a tree (empty / disconnected / wrong edge count), IndexError if root >= n.

(n: int, edges: Sequence[tuple[VertexId, VertexId]], root: VertexId | None=None) -> Tree

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

Executable usage: validation/unit/combin/test_graph_facade.py:114 · validation/unit/combin/test_graph_facade.py:40 · validation/unit/combin/test_graph_facade.py:75 · validation/parity/combinatorics/test_tree_pyo3.py:17 · validation/parity/combinatorics/test_tree_pyo3.py:197 · validation/parity/combinatorics/test_tree_pyo3.py:280

combin.Tree.from_graph

Validate an existing graph as an unweighted, undirected tree.

Detailed contract

Validate an existing graph as an unweighted, undirected tree and root it. The graph value is consumed, but the tree stores a canonical edge order so construction order and endpoint orientation are not tree identity.

(graph: Graph, root: VertexId | None=None) -> Tree

noether::combin::Tree::from_graph · Direct Rust declaration

pub fn from_graph(graph: Graph, root: Option<u32>) -> Result<Tree, TreeError>
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/Tree@1

Executable usage: validation/unit/combin/test_graph_facade.py:112 · validation/unit/combin/test_graph_facade.py:116 · validation/unit/combin/test_graph_facade.py:98

combin.Tree.from_json

Deserialize and revalidate a rooted tree.

(value: str) -> Tree

noether::combin::Tree · 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/Tree@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.Tree.heavy_light_decomposition

The heavy-light decomposition structure as a dict: {"head": list[int], "position": list[int], "chain": list[int]}, indexed by vertex id (head[v] the chain head, position[v] the linearised HLD position, chain[v] the chain id).

Detailed contract

The heavy-light decomposition structure as a dict: {"head": list[int], "position": list[int], "chain": list[int]}, indexed by vertex id (head[v] the chain head, position[v] the linearised HLD position, chain[v] the chain id).

The heavy-light decomposition structure: per-vertex chain head, position within the linearised HLD order, and the heavy child. This returns the HLD structure rather than a value-aggregation query engine. It is enough to decompose any u‥v tree path into O(log n) contiguous [lo, hi] position intervals via [HeavyLightDecomposition::path_intervals].

(self) -> dict[str, list[int]]

noether::combin::Tree::heavy_light_decomposition · Direct Rust declaration

pub fn heavy_light_decomposition(&self) -> HeavyLightDecomposition
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/Tree@1

Executable usage: validation/parity/combinatorics/test_tree_core_parity.py:29 · validation/parity/combinatorics/test_tree_pyo3.py:20 · validation/parity/combinatorics/test_tree_pyo3.py:253

combin.Tree.hld_path_intervals

Decompose the u‥v tree path into O(log n) contiguous HLD position intervals [lo, hi] (inclusive), as a list[(int, int)].

Detailed contract

Decompose the u‥v tree path into O(log n) contiguous HLD position intervals [lo, hi] (inclusive), as a list[(int, int)]. Their disjoint union is the path's vertex set under the HLD linearisation. Raises IndexError if u or v >= order.

(self, left: VertexId, right: VertexId) -> list[tuple[int, int]]

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

Executable usage: validation/parity/combinatorics/test_tree_pyo3.py:20 · validation/parity/combinatorics/test_tree_pyo3.py:266

combin.Tree.is_ancestor

True if a is an ancestor of d (a vertex is its own ancestor).

Detailed contract

True if a is an ancestor of d (a vertex is its own ancestor). O(1) via the preorder interval. Raises IndexError if a or d >= order.

true if a is an ancestor of d (a vertex is its own ancestor). O(1) via the preorder interval: a is an ancestor of d iff d lies in a’s subtree interval [tin[a], tout[a]).

(self, ancestor: VertexId, descendant: VertexId) -> bool

noether::combin::Tree::is_ancestor · Direct Rust declaration

pub fn is_ancestor(&self, a: u32, d: u32) -> 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/Tree@1

Executable usage: validation/parity/combinatorics/test_tree_core_parity.py:18 · validation/parity/combinatorics/test_tree_core_parity.py:269 · validation/parity/combinatorics/test_tree_core_parity.py:299 · validation/parity/combinatorics/test_tree_pyo3.py:18 · validation/parity/combinatorics/test_tree_pyo3.py:225

combin.Tree.kth_ancestor

v's k-th ancestor (parent for k == 1, v itself for k == 0), or None if k exceeds v's depth.

Detailed contract

v's k-th ancestor (parent for k == 1, v itself for k == 0), or None if k exceeds v's depth. O(log n) (binary lifting). Raises IndexError if v >= order.

v’s k-th ancestor (parent for k == 1), or None if k exceeds v’s depth. kth_ancestor(v, 0) == Some(v). O(log n) via the binary-lifting table.

(self, vertex: VertexId, k: int) -> VertexId | None

noether::combin::Tree::kth_ancestor · Direct Rust declaration

pub fn kth_ancestor(&self, v: u32, k: usize) -> Option<u32>
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/Tree@1

Executable usage: validation/parity/combinatorics/test_tree_core_parity.py:23 · validation/parity/combinatorics/test_tree_core_parity.py:270 · validation/parity/combinatorics/test_tree_core_parity.py:305 · validation/parity/combinatorics/test_tree_pyo3.py:18 · validation/parity/combinatorics/test_tree_pyo3.py:232

combin.Tree.lca

The lowest common ancestor of u and v — O(1) (Euler-tour sparse-table RMQ).

Detailed contract

The lowest common ancestor of u and v — O(1) (Euler-tour sparse-table RMQ). Raises IndexError if u or v >= order.

The lowest common ancestor of u and v. O(1) after the O(n log n) Euler-tour sparse-table prep done at construction. The LCA is the vertex of minimum depth on the Euler-tour segment between u’s and v’s first occurrences.

(self, left: VertexId, right: VertexId) -> VertexId

noether::combin::Tree::lca · Direct Rust declaration

pub fn lca(&self, u: u32, v: u32) -> u32
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/Tree@1

Executable usage: validation/unit/combin/test_graph_facade.py:104 · validation/parity/combinatorics/test_tree_core_parity.py:21 · validation/parity/combinatorics/test_tree_core_parity.py:225 · validation/parity/combinatorics/test_tree_core_parity.py:233 · validation/parity/combinatorics/test_tree_core_parity.py:268 · validation/parity/combinatorics/test_tree_core_parity.py:302

combin.Tree.order

The number of vertices.

Detailed contract

The number of vertices. Valid vertex ids are 0..order.

(self) -> int

noether::combin::Tree::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/Tree@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.Tree.root

The root vertex.

(self) -> VertexId

noether::combin::Tree::root · Direct Rust declaration

pub fn root(&self) -> u32
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/Tree@1

Executable usage: examples/10_padic_hensel_lifting.py:14 · examples/10_padic_hensel_lifting.py:15 · examples/10_padic_hensel_lifting.py:16 · examples/10_padic_hensel_lifting.py:3 · examples/distributed/f2_linear_algebra.py:21 · examples/distributed/f2_linear_algebra.py:40

combin.Tree.subtree

v's subtree as a preorder list[int] (it begins with v).

Detailed contract

v's subtree as a preorder list[int] (it begins with v). O(1) to obtain; length subtree_size(v). Raises IndexError if v >= order.

v’s subtree as a preorder slice (it begins with v). O(1) to obtain; length subtree_size(v).

(self, vertex: VertexId) -> list[VertexId]

noether::combin::Tree::subtree · Direct Rust declaration

pub fn subtree(&self, v: u32) -> &[u32]
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/Tree@1

Executable usage: validation/parity/combinatorics/test_tree_core_parity.py:18 · validation/parity/combinatorics/test_tree_pyo3.py:18 · validation/parity/combinatorics/test_tree_pyo3.py:221 · validation/parity/combinatorics/test_tree_pyo3.py:273

combin.Tree.subtree_size

The number of vertices in v's subtree (including v).

Detailed contract

The number of vertices in v's subtree (including v). O(1). Raises IndexError if v >= order.

The number of vertices in v’s subtree (including v). O(1).

(self, vertex: VertexId) -> int

noether::combin::Tree::subtree_size · Direct Rust declaration

pub fn subtree_size(&self, v: u32) -> 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/Tree@1

Executable usage: validation/parity/combinatorics/test_tree_core_parity.py:18 · validation/parity/combinatorics/test_tree_core_parity.py:266 · validation/parity/combinatorics/test_tree_core_parity.py:297 · validation/parity/combinatorics/test_tree_core_parity.py:298 · validation/parity/combinatorics/test_tree_pyo3.py:18 · validation/parity/combinatorics/test_tree_pyo3.py:220

combin.Tree.to_json

Serialize the tree's validated defining content.

(self) -> str

noether::combin::Tree · 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/Tree@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.Tree.tree_dp

The canonical tree DP: the post-order subtree fold instantiated as the subtree-size dynamic program — result[v] == subtree_size(v) for every vertex, computed by the deep-safe (explicit-stack, no recursion) reverse-preorder fold.

Detailed contract

The canonical tree DP: the post-order subtree fold instantiated as the subtree-size dynamic program — result[v] == subtree_size(v) for every vertex, computed by the deep-safe (explicit-stack, no recursion) reverse-preorder fold. Returns a list[int] indexed by vertex id.

This surfaces the kernel's generic Tree::fold through the canonical DP; the closure (leaf = 1, merge = +) is fixed because Python closures cannot cross the kernel's Fn boundary safely.

(self) -> list[int]

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

Executable usage: validation/parity/combinatorics/test_tree_pyo3.py:20 · validation/parity/combinatorics/test_tree_pyo3.py:272 · validation/parity/combinatorics/test_tree_pyo3.py:273