docs(tableau-algebra): highlight canonicalization input requirements

Author: Krastanov

crates/tableau_algebra/src/canonical.rs

@@ -7,6 +7,10 @@ use crate::rows::{forward_pass, has_x, has_z};
 
 /// Reduce all X columns, then all Z columns, in place.
 ///
+/// > **Warning:** Requires a valid full-rank frame: `n` destabilizers followed by
+/// > their `n` paired stabilizers on `n` qubits (`2n × n` Pauli entries).
+/// > Stabilizer-only and rank-deficient tableaux are unsupported.
+///
 /// This is QuantumClifford's `canonicalize!` form, used there for stabilizer
 /// inner products (Garcia et al., 2012). Returns `(x_rank, total_rank)`, the
 /// numbers of pivots after the X pass and after both passes. For a valid

crates/tableau_algebra/src/clipped.rs

@@ -8,6 +8,10 @@ use crate::rows::{multiply, site, swap};
 
 /// Put a pure stabilizer state in the clipped gauge, in place.
 ///
+/// > **Warning:** Requires a valid full-rank frame: `n` destabilizers followed by
+/// > their `n` paired stabilizers on `n` qubits (`2n × n` Pauli entries).
+/// > Stabilizer-only and rank-deficient tableaux are unsupported.
+///
 /// This is QuantumClifford's `canonicalize_clip!` form (Nahum et al., 2017;
 /// Li et al., 2019, Appendix A). A left-to-right pass fixes the left endpoints;
 /// a right-to-left pass shortens the rows while preserving those endpoints.
@@ -16,7 +20,7 @@ use crate::rows::{multiply, site, swap};
 /// different nonidentity Paulis there.
 ///
 /// Endpoint pairs describe the state's entanglement across cuts in the qubit
-/// ordering. The input must be a valid full-rank pure-state frame.
+/// ordering.
 ///
 /// ```
 /// use ppvm_tableau_2::Tableau;

crates/tableau_algebra/src/gottesman.rs

@@ -22,6 +22,10 @@ pub struct GottesmanForm {
 
 /// Put the stabilizers in Gottesman's standard form, reordering qubits.
 ///
+/// > **Warning:** Requires a valid full-rank frame: `n` destabilizers followed by
+/// > their `n` paired stabilizers on `n` qubits (`2n × n` Pauli entries).
+/// > Stabilizer-only and rank-deficient tableaux are unsupported.
+///
 /// Like QuantumClifford's `canonicalize_gott!`, first reduce X and move its
 /// pivot columns to the left. Then reduce Z on the remaining columns and
 /// move those pivots next. The pivot blocks are identity matrices. This form
@@ -30,7 +34,6 @@ pub struct GottesmanForm {
 ///
 /// Both halves of the frame follow the qubit permutations. These are physical
 /// qubit reorderings, so use the returned permutations to track qubit labels.
-/// This API accepts a pure-state frame, with one stabilizer per qubit.
 ///
 /// ```
 /// use ppvm_tableau_2::Tableau;

crates/tableau_algebra/src/rref.rs

@@ -7,6 +7,10 @@ use crate::rows::{eliminate, has_x, has_z, site, swap};
 
 /// Reduce selected qubit columns, alternating X and Z elimination.
 ///
+/// > **Warning:** Requires a valid full-rank frame: `n` destabilizers followed by
+/// > their `n` paired stabilizers on `n` qubits (`2n × n` Pauli entries).
+/// > Stabilizer-only and rank-deficient tableaux are unsupported.
+///
 /// This is QuantumClifford's `canonicalize_rref!` form (Audenaert and Plenio,
 /// 2005). Pivots go at the bottom. Returns the number of leading stabilizer
 /// rows that are identity on every selected qubit. Those rows generate the