feat(tableau-algebra): add four stabilizer canonicalizations

[Krastanov-agent]

Goal and initial prompt

PPVM has a tableau datastructure, but it does not support various types of canonicalization for that datastructure. In a new crate, called tableau_algebra, implement the various types of
canonicalization that QuantumClifford.jl support. Prioritize simplicity of the code and idiomatic nature of the port. The diff should be particularly straightforward to review, and the
sequence of commits should be easy to review one after the other (e.g. a commit to set boilerplate, followed by separate commits for implementation and tests of each type of
canonicalization). Have brief documentation for each one of them based on the QuantumClifford.jl doc.

QuantumClifford.jl defines a few different types of tableau wrappers, but in ppvm you can work directly with the tableau.

To validate the results make an independent script that generates random tableaux using QuantumClifford.jl and then canonicalizes them both with QuantumClifford.jl and with ppvm and
compares the results. Make sure to include sizes around word-size boundaries to detect off-by-one errors in bit indexing. Share these tests as a github gist.

Use the simplest indexing interface and row-operation interface that ppvm provides, and avoid reaching into internal details. If there are multiple options for datastructures to support,
support only the simplest ones. Avoid scope creep.

Prioritize simplicity of the code, not performance.

Some of the QuantumClifford.jl tests will not be portable to ppvm because of missing other features. Be simple in the tests you write and avoid mocking, boilerplate, or bespoke
reimplementation of other QuantumClifford.jl features.

---

Examples

Prepare a GHZ frame for the examples:

use ppvm_tableau_2::Tableau;
use ppvm_traits_2::Clifford;
use tableau_algebra::{
    canonicalize, canonicalize_rref, canonicalize_gott, canonicalize_clip,
};

let mut ghz = Tableau::new(3);
ghz.h(0);
ghz.cnot(0, 1);
ghz.cnot(1, 2);

Use X-then-Z canonicalization to obtain a standard stabilizer basis, as used in stabilizer-state inner-product calculations:

let mut tableau = ghz.clone();
let (x_rank, total_rank) = canonicalize(&mut tableau);
assert_eq!((x_rank, total_rank), (1, 3));
// Stabilizers: +XXX, +ZIZ, +IZZ.

Use selected-column RREF to isolate the stabilizers that survive tracing out selected qubits. The return value counts the leading surviving rows:

let mut tableau = ghz.clone();
let remaining = canonicalize_rref(&mut tableau, &[0]);
assert_eq!(remaining, 1);
// The leading stabilizer is +IZZ; it is identity on qubit 0.

Use Gottesman form to put the X and Z pivot blocks into identity form for stabilizer-code algebra. Its permutations track the reordered qubits:

let mut tableau = Tableau::new(3);
tableau.h(2);
let form = canonicalize_gott(&mut tableau);
assert_eq!((form.x_rank, form.z_rank), (1, 2));
assert_eq!(form.x_permutation, [2, 0, 1]);
assert_eq!(form.z_permutation, [0, 1, 2]);
// Stabilizers: +XII, +IZI, +IIZ.
// Final qubit q came from x_permutation[z_permutation[q]].

Use clipped gauge to expose stabilizer endpoints for entanglement calculations along the qubit ordering:

let mut tableau = ghz.clone();
canonicalize_clip(&mut tableau);
// Stabilizers: +XXX, +ZZI, +IZZ.
// Endpoint pairs: (0, 2), (0, 1), (1, 2).

[github-actions]

👋 Thanks for opening your first pull request against PPVM!

A quick note on contribution terms: by submitting this PR you
agree that your contribution is licensed under the
Apache License 2.0
and that you accept the
PPVM Contributor License Agreement.
Please skim those before a maintainer reviews — opening this PR
counts as your acceptance.

A few things that will speed up review:

• Read CONTRIBUTING.md
  for the workflow, build commands, and style notes.
• Run prek run --all-files locally; CI runs the same checks.
• Use Conventional Commits
  for commit messages.

We'll get to your PR as soon as we can. Thanks for contributing!

[Krastanov]

independent validation against QuantumClifford.jl (heavily fuzz tested) implementation done here https://gist.github.com/Krastanov-agent/de90f8949624dabc12540a42ca9dfcbd

[Krastanov]

note to the reviewer: unlike other canonicalization procedures, this one reorders columns. That reordering might need to be undone in the future, so the permutation is saved. This particular canonicalization type is needed for finding logical operators

[Krastanov]

a question for the reviewer: are there already existing implementation of the functions here -- they seem like standard getters one would expect from a tableau datastructure.

[Krastanov-agent]

QuantumClifford’s Stabilizer stores only generator rows. Its X-then-Z, selected-column RREF, and Gottesman routines accept rectangular commuting Hermitian inputs, including redundant generators. Their respective uses are basis/rank reduction, partial trace, and standard form for code construction. Clipped gauge also supports independent rectangular inputs, including mixed states (tests); its two-endpoints-per-qubit guarantee applies to pure states. All four forms exist here, but currently require complete 2n × n stabilizer/destabilizer frames.

QuantumClifford’s MixedDestabilizer(Stabilizer) constructor uses Gottesman reduction to determine rank r, discard redundant rows, and construct destabilizers plus n-r logical X/Z pairs. Destabilizer(Stabilizer) uses that construction when there are fewer rows than qubits and retains the active pairs. These conversions, Gottesman backtracking, optional phase skipping, and canonicalize_noncomm for noncommuting generators are missing here.

PPVM’s original tableau has a public resizable row vector. For the ppvm-tableau-2 path used here, a simple extension could accept mutable phased-Pauli rows with independent row and qubit counts. Elimination would use ordinary row operations; frame operations would separately update paired destabilizers. No wrapper hierarchy or prior frame completion is needed.