documentation improvements to close #258

Author: Fe-r-oz

docs/src/datastructures.md

@@ -11,37 +11,26 @@ necessary.
 
 ```@raw html
 <div class="mermaid">
-flowchart TB
+flowchart TD
     A["<code>Tableau Data Structure Selection</code>"]
     class A startEnd
-
-    A -->|<code>Are the states pure?</code>| B{ }
+    A --> B{"Is the state a stabilizer?"}
     class A,B startEnd
-
-    B -->|<code>Yes</code>| C["<code>Stabilizer</code>"]
-    B -->|<code>No</code>| D{ }
-    class B decision
-
-    D -->|<code>Are the states mixed?</code>| E{ }
-    class D,E decision
-
-    C --> C_desc1["<code>Ensures pure stabilizer states</code>"]
-    C --> C_desc2["<code>Requires user to check for consistency</code>"]
-    C --> C_desc3["<code>Efficient project! operations</code>"]
-    class C_desc1,C_desc2,C_desc3 description
-
-    C --> G["<code>Destabilizer</code>"]
-    G --> G_desc1["<code>No stabilizer canonicalization needed</code>"]
-    class G_desc1 description
-
-    E -->|<code>Yes</code>| F["<code>MixedStabilizer</code>"]
-    F --> F_desc1["<code>Explicitly tracks rank of mixed states</code>"]
-    F --> F_desc2["<code>Project! on non-Stabilizer commuting operators</code>"]
-    class F_desc1,F_desc2 description
-
-    E -->|<code>No</code>| H["<code>MixedDestabilizer</code>"]
-    H --> H_desc1["<code>Tracks destabilizer and logical operators</code>"]
-    H --> H_desc2["<code>Efficient project! operations</code>"]
+    B -->|Yes| C{"Pure state?"}
+    B -->|No| D{"Pure state?"}
+    class B,C,D decision
+    C -->|Yes| E["<code>Stabilizer</code>"]
+    E --> E_desc["<code>Pure stabilizer states<br/>Efficient 'project!' operations</code>"]
+    class E_desc description
+    C -->|No| F["<code>MixedStabilizer</code>"]
+    F --> F_desc["<code>Tracks rank of mixed states<br/>'Project!' on non-Stabilizer commuting operators</code>"]
+    class F_desc description
+    D -->|Yes| G["<code>Destabilizer</code>"]
+    G --> G_desc["<code>Pure stabilizer states<br/>Tracks destabilizers<br/>Efficient 'project!' operations</code>"]
+    class G_desc description
+    D -->|No| H["<code>MixedDestabilizer<code>"]
+    H --> H_desc["<code>Tracks destabilizers<br/>Tracks 'logical' operators<br/>Efficient 'project!' operations</code>"]
+    class H_desc description
 </div>
 ```
 

docs/src/mixed.md

@@ -2,7 +2,7 @@
 
 ```@meta
 DocTestSetup = quote
-    using QuantumClifford: @S_str, Destabilizer, MixedDestabilizer, MixedStabilizer, stabilizerview, destabilizerview, logicalxview, logicalzview, @T_str, _T_str, canonicalize!, Tableau
+    using QuantumClifford
 end
 ```
 
@@ -18,7 +18,7 @@ generators.
 # Options for constructing with MixedDestabilizer
 
 - Given a `Destabilizer` object (which  presumesfull rank), convert it
-into a `MixedDestabilizer` object. This allows for the possibility of 
+into a `MixedDestabilizer` object. This allows for the possibility of
 rank deficiency.
 
 ```jldoctest mix
@@ -66,8 +66,8 @@ julia> logicalzview(m)
 ```
 
 - Similar to the first option, but with the added capability to
-specify the "rank." This rank determines the number of rows
-associated with the `Stabilizer` and the number corresponding 
+specify the "rank". This rank determines the number of rows
+associated with the `Stabilizer` and the number corresponding
 to the logical operators.
 
 ```jldoctest mix
@@ -80,10 +80,12 @@ julia> MixedDestabilizer(T"ZI IX XX ZZ", 2)
 + ZZ
 ```
 
-If the macro string `@T_str` is not convenient, use the normal strings 
+If the macro string `@T_str` is not convenient, use the normal strings
 `_T_str`.
 
 ```jldoctest mix
+julia> using QuantumClifford: _T_str # hide
+
 julia> MixedDestabilizer(_T_str("ZI IX XX ZZ"), 2)
 𝒟ℯ𝓈𝓉𝒶𝒷
 + Z_
@@ -93,10 +95,10 @@ julia> MixedDestabilizer(_T_str("ZI IX XX ZZ"), 2)
 + ZZ
 ```
 
-- Given a `Stabilizer` object (whichmay have fewer rows than columns)
-, perform the necessary canonicalization to determine the 
-corresponding destabilizer and logical operators, resulting in a 
-complete MixedDestabilizer object.
+- Given a `Stabilizer` object (whichmay have fewer rows than columns),
+perform the necessary canonicalization to determine the corresponding
+destabilizer and logical operators, resulting in a complete
+MixedDestabilizer object.
 
 ```jldoctest mix
 julia> s = S"-XXX
@@ -116,9 +118,9 @@ julia> MixedDestabilizer(s, undoperm=false, reportperm=false)
 + Z_Z
 ```
 
-When `undoperm` is set to `false`, the column permutations are not reversed.
-As a result, the qubits may be reindexed according to the permutations
-made during the canonicalization process.
+When `undoperm` is set to `false`, the column permutations are not
+reversed. As a result, the qubits may be reindexed according to 
+the permutations made during the canonicalization process.
 
 ```jldoctest mix
 julia> MixedDestabilizer(s, undoperm=true, reportperm=false)
@@ -134,9 +136,9 @@ julia> MixedDestabilizer(s, undoperm=true, reportperm=false)
 + ZZ_
 ```
 
-When `undoperm` is set to `true`, the column permutations performed during 
-canonicalizationare automatically reversed before finalizing the 
-`MixedDestabilizer`.
+When `undoperm` is set to `true`, the column permutations performed
+during canonicalizationare automatically reversed before finalizing
+the `MixedDestabilizer`.
 
 ```jldoctest mix
 julia> MixedDestabilizer(canonicalize!(s))
@@ -152,12 +154,14 @@ julia> MixedDestabilizer(canonicalize!(s))
 + ZZ_
 ```
 
-- A low-level constructor that accepts a manually created `Tableau` object 
-and rank. Note that the `Tableau` object is not currently public. It 
-serves as the underlying data structure for all related objects but 
-does not assume commutativity or other properties.
+- A low-level constructor that accepts a manually created `Tableau`
+ object and rank. Note that the `Tableau` object is not currently
+public. It serves as the underlying data structure for all related
+objects but does not assume commutativity or other properties.
 
 ```jldoctest mix
+julia> using QuantumClifford: Tableau # hide
+
 julia> MixedDestabilizer(Tableau(Bool[0 0; 0 1; 1 1; 1 0],
                                  Bool[1 0; 0 0; 0 0; 1 1]), 2)
 𝒟ℯ𝓈𝓉𝒶𝒷
@@ -170,9 +174,9 @@ julia> MixedDestabilizer(Tableau(Bool[0 0; 0 1; 1 1; 1 0],
 
 # Options for constructing with MixedStabilizer
 
-- Given a `Stabilizer` object (which  presumesfull rank), convert it
-into a `MixedStabilizer` object. This allows for the possibility of 
-rank deficiency.
+- Given a `Stabilizer` object (which  presumesfull rank), convert
+ it into a `MixedStabilizer` object. This allows for the
+possibility of  rank deficiency.
 
 ```jldoctest mix
 julia> s = S"-XXX
@@ -189,10 +193,10 @@ julia> MixedStabilizer(s, 2)
 - Z_Z
 ```
 
-- Similar to the first option, but with the added capability to
-specify the "rank." This rank determines the number of rows
-associated with the `Stabilizer` and the number corresponding 
-to the logical operators.
+- Similar to the first option, but with the added capability
+to specify the "rank." This rank determines the number of
+rows associated with the `Stabilizer` and the number
+corresponding  to the logical operators.
 
 ```jldoctest mix
 julia> MixedStabilizer(S"-XXX -ZIZ IZZ")
@@ -207,7 +211,7 @@ julia> MixedStabilizer(S"-XXX -ZIZ IZZ", 2)
 
 - A low-level constructor that accepts a manually created `Tableau`
 object and rank. Note that the `Tableau` object is not currently
-public. It serves as the underlying data structure for all related 
+public. It serves as the underlying data structure for all related
 objects but does not assume commutativity or other properties.
 
 ```jldoctest mix

docs/src/stab-algebra-manual.md

@@ -2,7 +2,7 @@
 
 ```@meta
 DocTestSetup = quote
-    using QuantumClifford: @S_str, Stabilizer, Destabilizer, MixedDestabilizer, MixedStabilizer, stabilizerview, destabilizerview, logicalxview, logicalzview, @T_str, _T_str, @P_str, PauliOperator, ⊗, comm, prodphase, xview, xbit, getindex, setindex!, firstindex, lastindex, stab_to_gf2, canonicalize!, project!, Register, apply!, bitview, sMX, traceout!, generate!, tHadamard, tPhase, tCNOT, permute, apply!, CliffordOperator, sHadamard, sCNOT, phases, tId1, @C_str, tab, Tableau
+    using QuantumClifford
 end
 ```
 
@@ -146,6 +146,8 @@ number of different constructors.
     See also the [data structures discussion page](@ref Choosing-Appropriate-Data-Structure).
 
 ```jldoctest
+julia> using QuantumClifford: Tableau # hide
+
 julia> S"-XX
          +ZZ"
 - XX
@@ -173,6 +175,16 @@ julia> Stabilizer([0x2, 0x0],
                        0 0 1 1])
 - XX
 + ZZ
+
+julia> Stabilizer(T"-XX ZZ")
+- XX
++ ZZ
+
+julia> Stabilizer(Tableau([0x2, 0x0],
+                  Bool[1 1; 0 0],
+                  Bool[0 0; 1 1]))
+- XX
++ ZZ
 ```
 
 Direct sums can be performed,
@@ -206,36 +218,6 @@ julia> s[[3,1],[2]]
 
 julia> s[3][3]
 (false, true)
-
-julia> getindex(s, 1)
-- XYZ
-
-julia> getindex(s, 3, 1)
-(true, false)
-
-julia> setindex!(s, P"Z", 1)
-+ Z__
-- Z_X
-+ X_Z
-
-julia> setindex!(s, P"ZYX", 1)
-+ ZYX
-- Z_X
-+ X_Z
-
-julia> setindex!(s, (true, true), 1, 1)
-+ YYX
-- Z_X
-+ X_Z
-
-julia> firstindex(s)
-1
-
-julia> lastindex(s)
-3
-
-julia> lastindex(s, 2)
-3
 ```
 
 Consistency at creation is not verified so nonsensical stabilizers can be
@@ -708,18 +690,29 @@ julia> d = Destabilizer(s)
 ```
 
 - A low-level constructor that accepts a manually created `Tableau`
-object. Note thatthe `Tableau` object is not currently public. It serves
-as the underlying data structure for all related objects but does not
-assume commutativity or other properties.
+object. Note thatthe `Tableau` object is not currently public. It
+serves as the underlying data structure for all related objects
+but does not assume commutativity or other properties.
 
 ```jldoctest destab
-julia> d₁ = Destabilizer(Tableau(Bool[0 0; 0 1; 1 1; 0 0], Bool[1 0; 0 0; 0 0; 0 1]))
+julia> using QuantumClifford: Tableau # hide
+
+julia> d₁ = Destabilizer(Tableau(Bool[0 0; 0 1; 1 1; 0 0],
+                                Bool[1 0; 0 0; 0 0; 0 1]))
 𝒟ℯ𝓈𝓉𝒶𝒷
 + Z_
 + _X
 𝒮𝓉𝒶𝒷
 + XX
 + _Z
+
+julia> d₂ = Destabilizer(T"ZX ZI -ZZ -XY")
+𝒟ℯ𝓈𝓉𝒶𝒷
++ ZX
++ Z_
+𝒮𝓉𝒶𝒷
+- ZZ
+- XY
 ```
 
 They have convenience methods to extract only the stabilizer and destabilizer

src/QuantumClifford.jl

@@ -355,67 +355,6 @@ julia> s[1,1] = (true, false); s
 + __
 ```
 
-Stabilizer can be copied and assigned.
-
-```jldoctest stabilizer
-julia> s = S"-XXX
-             +ZZI
-             -IZZ";
-
-julia> s1 = copy(s)
-- XXX
-+ ZZ_
-- _ZZ
-```
-
-`Length` and `size` of stabilizer can be determined.
-
-```jldoctest stabilizer
-julia> length(s)
-3
-
-julia> size(s)
-(3, 3)
-```
-
-Indexing operations on stabilizer via `setindex!` and `getindex`.
-
-```jldoctest stabilizer
-julia> s = S"-XYZ
-             -ZIX
-             +XIZ";
-
-julia> getindex(s, 1)
-- XYZ
-
-julia> getindex(s, 3, 1)
-(true, false)
-
-julia> setindex!(s, P"Z", 1)
-+ Z__
-- Z_X
-+ X_Z
-
-julia> setindex!(s, P"ZYX", 1)
-+ ZYX
-- Z_X
-+ X_Z
-
-julia> setindex!(s, (true, true), 1, 1)
-+ YYX
-- Z_X
-+ X_Z
-
-julia> firstindex(s)
-1
-
-julia> lastindex(s)
-3
-
-julia> lastindex(s, 2)
-3
-```
-
 There are no automatic checks for correctness (i.e. independence of all rows,
 commutativity of all rows, hermiticity of all rows). The rank (number of rows)
 is permitted to be less than the number of qubits (number of columns):