noncliff: enhanced error message for inapplicable Project! of GeneralizedStabilizer

src/QuantumClifford.jl

@@ -98,6 +98,22 @@ function __init__()
     BIG_INT_MINUS_ONE[] = BigInt(-1)
     BIG_INT_TWO[] = BigInt(2)
     BIG_INT_FOUR[] = BigInt(4)
+
+    # Register error hint for the `project!` method for GeneralizedStabilizer
+    if isdefined(Base.Experimental, :register_error_hint)
+        Base.Experimental.register_error_hint(MethodError) do io, exc, argtypes, kwargs
+            if exc.f === project! && argtypes[1] <: GeneralizedStabilizer
+                print(io, """
+                \nThe method `project!` is not appropriate for use with`GeneralizedStabilizer`.
+                You probably are looking for `projectrand!`.
+                `project!` in this library is a low-level "linear algebra" method to verify
+                whether a measurement operator commutes with a set of stabilizers, and to
+                potentially simplify the tableau and provide the index of the anticommuting
+                term in that tableau. This linear algebra operation is not defined for
+                `GeneralStabilizer` as there is no single tableau to provide an index into.""")
+            end
+        end
+    end
 end
 
 const NoZeroQubit = ArgumentError("Qubit indices have to be larger than zero, but you are attempting to create a gate acting on a qubit with a non-positive index. Ensure indexing always starts from 1.")

src/nonclifford.jl

@@ -215,7 +215,7 @@ with ϕᵢⱼ | Pᵢ | Pⱼ:
  0.853553+0.0im | + _ | + _
  0.146447+0.0im | + Z | + Z
 
-julia> expect(P"-X", sm)
+julia> χ′ = expect(P"-X", sm)
 0.7071067811865475 + 0.0im
 
 julia> prob₁ = (real(χ′)+1)/2
@@ -236,6 +236,10 @@ function _proj(sm::GeneralizedStabilizer, p::PauliOperator)
     error("This functionality is not implemented yet")
 end
 
+function project!(s::GeneralizedStabilizer, p::PauliOperator)
+    throw(MethodError(project!, (s, p)))
+end
+
 nqubits(sm::GeneralizedStabilizer) = nqubits(sm.stab)
 
 abstract type AbstractPauliChannel <: AbstractOperation end
@@ -424,7 +428,9 @@ of a [`GeneralizedStabilizer`](@ref), representing the inverse sparsity
 of `χ`. It provides a measure of the state's complexity, with bounds
 `Λ(χ) ≤ 4ⁿ`.
 
-```jldoctest
+```jldoctest heuristic
+julia> using QuantumClifford: invsparsity; # hide
+
 julia> sm = GeneralizedStabilizer(S"X")
 A mixture ∑ ϕᵢⱼ Pᵢ ρ Pⱼ† where ρ is
 𝒟ℯ𝓈𝓉𝒶𝒷
@@ -442,7 +448,7 @@ Similarly, it calculates the number of non-zero elements in the density
 matrix `ϕᵢⱼ`​ of a PauliChannel, providing a measure of the channel
 complexity.
 
-```jldoctest
+```jldoctest heuristic
 julia> invsparsity(pcT)
 4
 ```

test/test_nonclifford.jl

@@ -59,3 +59,4 @@ end
 @test_throws ArgumentError PauliChannel(((P"X", P"Z"), (P"X", P"Z")), (1,))
 @test_throws ArgumentError UnitaryPauliChannel((P"X", P"ZZ"), (1,2))
 @test_throws ArgumentError UnitaryPauliChannel((P"X", P"Z"), (1,))
+@test_throws MethodError project!(GeneralizedStabilizer(S"X"), P"X")