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.
noether::combin::Tree · Direct Rust declaration
| 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.
noether::combin::Tree · Python projection
| 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.
noether::combin::Tree::center · Direct Rust declaration
| 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.
noether::combin::Tree::centroid · Direct Rust declaration
| 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.
noether::combin::Tree::centroid_decomposition · Direct Rust declaration
| 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).
noether::combin::Tree::depth · Direct Rust declaration
| 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.
noether::combin::Tree::diameter · Direct Rust declaration
| 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).
noether::combin::Tree::distance · Direct Rust declaration
| 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.
noether::combin::Tree · Python projection
| 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.
noether::combin::Tree · Python projection
| 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.
noether::combin::Tree::from_graph · Direct Rust declaration
| 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.
noether::combin::Tree · Python projection
| 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].
noether::combin::Tree::heavy_light_decomposition · Direct Rust declaration
| 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.
noether::combin::Tree · Python projection
| 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]).
noether::combin::Tree::is_ancestor · Direct Rust declaration
| 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.
noether::combin::Tree::kth_ancestor · Direct Rust declaration
| 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.
noether::combin::Tree::lca · Direct Rust declaration
| 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.
noether::combin::Tree::order · Direct Rust declaration
| 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.
noether::combin::Tree::root · Direct Rust declaration
| 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).
noether::combin::Tree::subtree · Direct Rust declaration
| 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).
noether::combin::Tree::subtree_size · Direct Rust declaration
| 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.
noether::combin::Tree · Python projection
| 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.
noether::combin::Tree · Python projection
| 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