From db6b01c49afc319752246b681529b8331d3686b8 Mon Sep 17 00:00:00 2001
From: Feroz Ahmad <93876775+Fe-r-oz@users.noreply.github.com>
Date: Sat, 3 Aug 2024 23:36:11 +0500
Subject: [PATCH] improving `doctests` for `Enumeration.jl` (#327)

Co-authored-by: Stefan Krastanov <github.acc@krastanov.org>
---
 src/enumeration.jl     | 42 ++++++++++++++++++++++++++++++++++++++++--
 test/test_enumerate.jl |  4 ++++
 2 files changed, 44 insertions(+), 2 deletions(-)

diff --git a/src/enumeration.jl b/src/enumeration.jl
index a7850082d..771bf40a1 100644
--- a/src/enumeration.jl
+++ b/src/enumeration.jl
@@ -9,6 +9,18 @@ const all_single_qubit_patterns = (
 
 """Generate a symbolic single-qubit gate given its index. Optionally, set non-trivial phases.
 
+```jldoctest
+julia> enumerate_single_qubit_gates(6)
+sPhase on qubit 1
+X₁ ⟼ + Y
+Z₁ ⟼ + Z
+
+julia> enumerate_single_qubit_gates(6, qubit=2, phases=(true, true))
+SingleQubitOperator on qubit 2
+X₁ ⟼ - Y
+Z₁ ⟼ - Z
+```
+
 See also: [`enumerate_cliffords`](@ref)."""
 function enumerate_single_qubit_gates(index; qubit=1, phases::Tuple{Bool,Bool}=(false,false))
     @assert index<=6 "Only 6 single-qubit gates exit, up to the choice of phases"
@@ -37,9 +49,21 @@ function enumerate_single_qubit_gates(index; qubit=1, phases::Tuple{Bool,Bool}=(
     end
 end
 
-"""The size of the Clifford group over a given number of qubits, possibly modulo the phases.
+"""The size of the Clifford group `𝒞` over a given number of qubits, possibly modulo the phases.
+
+For n qubits, not accounting for phases is `2ⁿⁿΠⱼ₌₁ⁿ(4ʲ-1)`. There are `4ⁿ` different phase configurations.
+
+```jldoctest
+julia> clifford_cardinality(7)
+457620995529680351512370381586432000
+```
 
-For n qubits, not accounting for phases is 2ⁿⁿΠⱼ₌₁ⁿ(4ʲ-1). There are 4ⁿ different phase configurations.
+When not accounting for phases (`phases = false`) the result is the same as the size of the Symplectic group `Sp(2n) ≡ 𝒞ₙ/𝒫ₙ`, where `𝒫ₙ` is the Pauli group over `n` qubits.
+
+```jldoctest
+julia> clifford_cardinality(7, phases=false)
+27930968965434591767112450048000
+```
 
 See also: [`enumerate_cliffords`](@ref).
 """
@@ -83,6 +107,20 @@ end
 
 The algorithm is detailed in [koenig2014efficiently](@cite).
 
+```jldoctest
+julia> symplecticGS(P"X", padded_n=3)
+X₁ ⟼ + X__
+X₂ ⟼ + _X_
+X₃ ⟼ + __X
+Z₁ ⟼ + Z__
+Z₂ ⟼ + _Z_
+Z₃ ⟼ + __Z
+
+julia> symplecticGS(P"Z")
+X₁ ⟼ + Z
+Z₁ ⟼ + X
+```
+
 See also: [`enumerate_cliffords`](@ref), [`clifford_cardinality`](@ref)."""
 function symplecticGS(pauli::PauliOperator; padded_n=nqubits(pauli))
     n = nqubits(pauli)
diff --git a/test/test_enumerate.jl b/test/test_enumerate.jl
index b1c0ac932..e9f3c7df3 100644
--- a/test/test_enumerate.jl
+++ b/test/test_enumerate.jl
@@ -4,4 +4,8 @@
     @test length(collect(enumerate_cliffords(2))) == length(collect(enumerate_phases(enumerate_cliffords(2))))/2^4 == 720
     @test first(enumerate_cliffords(3)) == C"X__ __Z _Z_ Z__ __X _X_"
     @test first(enumerate_cliffords(5)) == C"X____ ____Z ___Z_ __Z__ _Z___ Z____ ____X ___X_ __X__ _X___"
+    for n in 1:10
+        symplectic_cardinality = clifford_cardinality(n, phases=false)
+        @test clifford_cardinality(n) == symplectic_cardinality*(2^(2n))
+    end
 end