introduce permutesystems (#490)

Author: Krastanov

CHANGELOG.md

@@ -1,10 +1,14 @@
 # Planned changes for v1.0.0:
 
-- `permute` will be a wrapper around to `QuantumInterface.permutesubsystems`. Documentation for `permute!` would be similarly updated
+- `permute` will be a wrapper around to `QuantumInterface.permutesystems`. Documentation for `permute!` would be similarly updated
 - reworking the rest of `NoisyCircuits` and moving it out of `Experimental`
 
 # News
 
+## v0.9.19 - 2025-04-08
+
+- `permutesystems` and `permutesystems!` are no implemented, deprecating `permute` and `permute!`
+
 ## v0.9.18 - 2025-02-19
 
 - Fixes for rare crashes in the python BP decoders.

Project.toml

@@ -1,7 +1,7 @@
 name = "QuantumClifford"
 uuid = "0525e862-1e90-11e9-3e4d-1b39d7109de1"
 authors = ["Stefan Krastanov <[email protected]> and QuantumSavory community members"]
-version = "0.9.18"
+version = "0.9.19"
 
 [deps]
 Combinatorics = "861a8166-3701-5b0c-9a16-15d98fcdc6aa"

docs/src/stab-algebra-manual.md

@@ -513,7 +513,7 @@ julia> tHadamard * tPhase
 X₁ ⟼ - Y
 Z₁ ⟼ + X
 
-julia> permute(tCNOT, [2,1])
+julia> permutesubsystem(tCNOT, [2,1])
 X₁ ⟼ + X_
 X₂ ⟼ + XX
 Z₁ ⟼ + ZZ

src/QuantumClifford.jl

@@ -15,7 +15,11 @@ using Combinatorics: combinations
 using Base.Cartesian
 using DocStringExtensions
 
-import QuantumInterface: tensor, ⊗, tensor_pow, apply!, nqubits, expect, project!, reset_qubits!, traceout!, ptrace, apply!, projectX!, projectY!, projectZ!, entanglement_entropy, embed
+import QuantumInterface: tensor, ⊗, tensor_pow,
+    nqubits, expect, project!, reset_qubits!, traceout!, ptrace,
+    apply!, projectX!, projectY!, projectZ!,
+    embed, permutesystems,
+    entanglement_entropy
 
 export
     @P_str, PauliOperator, ⊗, I, X, Y, Z,
@@ -37,13 +41,14 @@ export
     tensor, tensor_pow,
     logdot, expect,
     apply!,
+    permutesystems, permutesystems!,
     # Low Level Function Interface
     generate!, project!, reset_qubits!, traceout!,
     projectX!, projectY!, projectZ!,
     projectrand!, projectXrand!, projectYrand!, projectZrand!,
     puttableau!, embed,
     # Clifford Ops
-    CliffordOperator, @C_str, permute,
+    CliffordOperator, @C_str,
     tCNOT, tCPHASE, tSWAP, tHadamard, tPhase, tId1,
     # Symbolic Clifford Ops
     AbstractSymbolicOperator, AbstractSingleQubitOperator, AbstractTwoQubitOperator,
@@ -936,20 +941,6 @@ the following values based on the index `i`:
     return lowbit, ibig, ismall, ismallm
 end
 
-"""Permute the qubits (i.e., columns) of the tableau in place."""
-function Base.permute!(s::Tableau, perm::AbstractVector)
-    for r in 1:size(s,1)
-        s[r] = s[r][perm] # TODO make a local temporary buffer row instead of constantly allocating new rows
-    end
-    s
-end
-
-"""Permute the qubits (i.e., columns) of the state in place."""
-function Base.permute!(s::AbstractStabilizer, perm::AbstractVector)
-    permute!(tab(s), perm)
-    s
-end
-
 function check_allrowscommute(stabilizer::Tableau)
     for i in eachindex(stabilizer)
         for j in eachindex(stabilizer)
@@ -1349,6 +1340,7 @@ include("fastmemlayout.jl")
 include("dense_cliffords.jl")
 # special one- and two- qubit operators
 include("symbolic_cliffords.jl")
+# linear algebra and array-like operations
 include("linalg.jl")
 # circuits
 include("operator_traits.jl")

src/canonicalization.jl

@@ -240,7 +240,7 @@ function _canonicalize_gott!(stabilizer::Stabilizer; phases::Val{B}=Val(true)) w
         end
     end
     xperm, r = gott_standard_form_indices((@view xzs[1:end÷2,:]),rows,columns)
-    permute!(stabilizer,xperm)
+    permutesystems!(stabilizer,xperm)
     i = r+1
     for j in r+1:columns
         # find first row with Z in col `j`
@@ -257,7 +257,7 @@ function _canonicalize_gott!(stabilizer::Stabilizer; phases::Val{B}=Val(true)) w
         end
     end
     zperm, s = gott_standard_form_indices((@view xzs[end÷2+1:end,:]),rows,columns,skip=r)
-    permute!(stabilizer,zperm)
+    permutesystems!(stabilizer,zperm)
     # we have r+s==rows (or we have trailing rows that are zeroed)
     stabilizer, r, s, xperm, zperm
 end

src/dense_cliffords.jl

@@ -106,11 +106,6 @@ function apply!(r::CliffordOperator, l::AbstractCliffordOperator; phases=false)
     r
 end
 
-# TODO create Base.permute! and getindex(..., permutation_array)
-function permute(c::CliffordOperator,p) # TODO this is a slow stupid implementation
-    CliffordOperator(Tableau([tab(c)[i][p] for i in 1:2*nqubits(c)][vcat(p,p.+nqubits(c))]))
-end
-
 """Nonvectorized version of `apply!` used for unit tests."""
 function _apply_nonthread!(stab::AbstractStabilizer, c::CliffordOperator; phases::Bool=true)
     nqubits(stab)==nqubits(c) || throw(DimensionMismatch("The tableau and the Clifford operator need to act on the same number of qubits. Consider specifying an array of indices as a third argument to the `apply!` function to avoid this error."))

src/linalg.jl

@@ -1,3 +1,28 @@
+function permutesystems(c::CliffordOperator,p) # TODO this is a slow stupid implementation
+    CliffordOperator(Tableau([tab(c)[i][p] for i in 1:2*nqubits(c)][vcat(p,p.+nqubits(c))]))
+end
+
+@deprecate permute(c::CliffordOperator,p) permutesystems(c,p)
+
+function permutesystems!(s::Tableau, perm::AbstractVector)
+    for r in 1:size(s,1)
+        s[r] = s[r][perm] # TODO make a local temporary buffer row instead of constantly allocating new rows
+    end
+    s
+end
+
+function permutesystems!(s::AbstractStabilizer, perm::AbstractVector)
+    permutesystems!(tab(s), perm)
+    s
+end
+
+import Base: permute!
+@deprecate permute!(s::Tableau, perm::AbstractVector) permutesystems!(s, perm)
+@deprecate permute!(s::AbstractStabilizer, perm::AbstractVector) permutesystems!(s, perm)
+
+# TODO upstream to QuantumInterface for (state::Any, perm)
+permutesystems(s::AbstractStabilizer, perm) = permutesystems!(s, perm)
+
 """
 $TYPEDSIGNATURES