groups · Permutation

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

Worked example

The complete checked program Construct S4 natively and inspect its stabilizer chain consequences uses this API directly.

# SPDX-License-Identifier: MIT
# Copyright (c) 2026 Benjamin Antieau and Deven Manam
"""Construct S4 natively and inspect its stabilizer chain consequences."""

from noether.groups import Permutation, PermutationGroup


def main() -> None:
    group = PermutationGroup.from_generators(
        4,
        [Permutation.from_images([1, 0, 2, 3]), Permutation.from_images([1, 2, 3, 0])],
    )
    assert group.order == 24
    assert group.is_transitive
    assert group.stabilizer(0).order == 6
    random = group.uniform_random_element(seed=2026)
    assert random.element in group
    print(f"|S4|={group.order}; |Stab(0)|={group.stabilizer(0).order}; sample={random.element}")


if __name__ == "__main__":
    main()

Run it with .venv/bin/python examples/19_permutation_groups.py.

groups.Permutation

A permutation of 0..degree, stored as an image vector.

Detailed contract

A permutation of 0..degree, stored as an image vector.

Construct via Permutation.from_images. The composition convention is right action — (g * h).apply(i) = h.apply( g.apply(i)) — matching GAP and the Schreier–Sims literature.

PythonRust

class Permutation

noether::groups::Permutation · Direct Rust declaration

pub struct Permutation { /* private fields */ }

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, perm-core
GIL	attached / bounded
Semantic ID	noether/groups/Permutation@1

Executable usage: examples/19_permutation_groups.py:11 · examples/19_permutation_groups.py:5 · examples/20_conjugacy_classes.py:11 · examples/20_conjugacy_classes.py:5 · examples/34_finite_group_cohomology.py:5 · examples/34_finite_group_cohomology.py:9

groups.Permutation.__call__

Call self as a function.

PythonRust

(self, point: int) -> int

noether::groups::Permutation · 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, perm-core
GIL	attached / bounded
Semantic ID	noether/groups/Permutation@1

Executable usage: validation/unit/infra/test_discovery.py:57 · validation/unit/infra/test_public_api_index.py:155 · validation/unit/infra/test_public_api_index.py:169

groups.Permutation.__mul__

Return self*value.

PythonRust

(self, other: Permutation) -> Permutation

noether::groups::Permutation · 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, perm-core
GIL	attached / bounded
Semantic ID	noether/groups/Permutation@1

Executable usage: validation/unit/infra/test_public_api_index.py:214

groups.Permutation.apply

The image of p under this permutation.

Detailed contract

The image of p under this permutation. Raises IndexError if p >= degree.

The image of p under this permutation, panicking only on the invariant violation “p is outside the domain”. The orbit / sift hot paths call this for every step.

PythonRust

(self, point: int) -> int

noether::groups::Permutation::apply · Direct Rust declaration

pub fn apply(&self, p: u32) -> u32

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, perm-core
GIL	attached / bounded
Semantic ID	noether/groups/Permutation@1

Executable usage: examples/05_sparse_exact_operators.py:16 · validation/unit/commalg/test_local_algebra.py:94 · validation/unit/commalg/test_local_algebra.py:97 · validation/unit/commalg/test_polynomial_facade.py:199 · validation/unit/commalg/test_quotient_facade.py:186 · validation/unit/groups/test_weight_characters.py:39

groups.Permutation.compose

The composition self * other under the right-action convention.

Detailed contract

The composition self * other under the right-action convention. Raises ValueError on a degree mismatch.

Compose two permutations: (self * other)[i] = other[self[i]] — right-action convention. §Errors GroupError::DegreeMismatch if the two permutations act on domains of different sizes.

PythonRust

(self, other: Permutation) -> Permutation

noether::groups::Permutation::compose · Direct Rust declaration

pub fn compose(&self, other: &Perm) -> Result<Perm, GroupError>

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, perm-core
GIL	attached / bounded
Semantic ID	noether/groups/Permutation@1

Executable usage: validation/unit/commalg/test_context_tower_workload.py:3 · validation/unit/commalg/test_polynomial_facade.py:200 · validation/unit/commalg/test_power_series_facade.py:151 · validation/unit/commalg/test_power_series_facade.py:245 · validation/unit/commalg/test_power_series_facade.py:248 · validation/unit/groups/test_permutation_group_facade.py:41

groups.Permutation.degree

The permutation's degree — the size of its domain.

Detailed contract

The permutation’s degree — the size of its underlying domain.

PythonRust

(self) -> int

noether::groups::Permutation::degree · Direct Rust declaration

pub fn degree(&self) -> usize

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, perm-core
GIL	attached / bounded
Semantic ID	noether/groups/Permutation@1

Executable usage: examples/14_weighted_polynomials.py:16 · examples/14_weighted_polynomials.py:18 · examples/15_groebner_twisted_cubic.py:15 · examples/15_groebner_twisted_cubic.py:28 · examples/31_local_fields_and_precision.py:37 · examples/33_simplicial_cohomology_operations.py:26

groups.Permutation.from_images

Build a permutation from its image vector.

Detailed contract

Build a permutation from its image vector.

images[i] is the image of i under the permutation, so len(images) is the degree. Raises ValueError if images is not a permutation of 0..len(images) (out-of-range or repeated image).

Build a permutation from an image vector. §Errors GroupError::NotAPermutation if images contains a point >= images.len() (out of range) or repeats any value (not a bijection).

PythonRust

(images: Sequence[int]) -> Permutation

noether::groups::Permutation::from_images · Direct Rust declaration

pub fn from_images(images: &[u32]) -> Result<Perm, GroupError>

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, perm-core
GIL	attached / bounded
Semantic ID	noether/groups/Permutation@1

Executable usage: examples/19_permutation_groups.py:11 · examples/20_conjugacy_classes.py:11 · examples/34_finite_group_cohomology.py:9 · validation/unit/groups/test_acceptance_workload.py:122 · validation/unit/groups/test_acceptance_workload.py:139 · validation/unit/groups/test_acceptance_workload.py:162

groups.Permutation.identity

The identity permutation on 0..degree.

Detailed contract

The identity permutation on 0..degree.

PythonRust

(degree: int) -> Permutation

noether::groups::Permutation::identity · Direct Rust declaration

pub fn identity(degree: usize) -> Perm

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, perm-core
GIL	attached / bounded
Semantic ID	noether/groups/Permutation@1

Executable usage: examples/01_bezout_certificates.py:10 · examples/01_bezout_certificates.py:12 · examples/01_bezout_certificates.py:14 · examples/01_bezout_certificates.py:9 · examples/02_ball_arithmetic.py:3 · examples/distributed/f2_linear_algebra.py:20

groups.Permutation.images

The image vector as a list[int] of length degree.

Detailed contract

Borrow the image vector.

PythonRust

(self) -> list[int]

noether::groups::Permutation::images · Direct Rust declaration

pub fn images(&self) -> &[u32]

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, perm-core
GIL	attached / bounded
Semantic ID	noether/groups/Permutation@1

Executable usage: validation/unit/commalg/test_polynomial_facade.py:198 · validation/unit/commalg/test_polynomial_homomorphism.py:30 · validation/unit/groups/test_acceptance_workload.py:90 · validation/unit/groups/test_acceptance_workload.py:95 · validation/unit/groups/test_permutation_group_facade.py:49 · validation/unit/groups/test_permutation_group_facade.py:54

groups.Permutation.inverse

The inverse permutation.

PythonRust

(self) -> Permutation

noether::groups::Permutation::inverse · Direct Rust declaration

pub fn inverse(&self) -> Perm

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, perm-core
GIL	attached / bounded
Semantic ID	noether/groups/Permutation@1

Executable usage: examples/distributed/f2_linear_algebra.py:37 · examples/distributed/f2_linear_algebra.py:39 · validation/unit/commalg/test_context_tower_workload.py:121 · validation/unit/commalg/test_context_tower_workload.py:122 · validation/unit/commalg/test_context_tower_workload.py:75 · validation/unit/commalg/test_context_tower_workload.py:77

groups.Permutation.is_identity

True iff this is the identity permutation on its domain.

Detailed contract

true iff this is the identity permutation on its domain.

PythonRust

(self) -> bool

noether::groups::Permutation::is_identity · Direct Rust declaration

pub fn is_identity(&self) -> bool

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, perm-core
GIL	attached / bounded
Semantic ID	noether/groups/Permutation@1

Executable usage: examples/26_elliptic_descent_functions.py:39 · validation/unit/groups/test_acceptance_workload.py:103 · validation/unit/numthy/test_elliptic_curve_facade.py:108 · validation/unit/numthy/test_elliptic_curve_facade.py:93 · validation/corpus/groups/hurwitz-degree-nine-generating-triple.py:20

groups.Permutation.order

The (multiplicative) order of this permutation — the smallest k ≥ 1 with σ^k = identity.

Detailed contract

The (multiplicative) order of this permutation — the smallest k ≥ 1 with σ^k = identity. Equals the LCM of cycle lengths in the cycle decomposition.

The (multiplicative) order of this permutation — the smallest k ≥ 1 with σ^k = identity. Computed as the LCM of cycle lengths in the cycle decomposition; runs in O(degree).

PythonRust

(self) -> int

noether::groups::Permutation::order · Direct Rust declaration

pub fn order(&self) -> BigUInt

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, perm-core
GIL	attached / bounded
Semantic ID	noether/groups/Permutation@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