fix #258: Documentation on myriad ways to construct Stab/Destab/MixedDestab objects

docs/src/datastructures.md

@@ -9,6 +9,31 @@ states, [`Destabilizer`](@ref) should be the appropriate data structure. If
 mixed stabilizer states are involved, [`MixedStabilizer`](@ref) would be
 necessary.
 
+```@raw html
+<div class="mermaid">
+flowchart TD
+    A["<code>Tableau Data Structure Selection</code>"]
+    class A startEnd
+    A --> B{"Is the state a stabilizer?"}
+    class A,B startEnd
+    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>
+```
+
 [`Stabilizer`](@ref) is simply a list of Pauli operators in a tableau form. As a
 data structure it does not enforce the requirements for a pure stabilizer state
 (the rows of the tableau do not necessarily commute, nor are they forced to be

docs/src/index.md

@@ -6,14 +6,47 @@ DocTestSetup = quote
 end
 ```
 
-QuantumClifford.jl is a Julia library for simulation of Clifford circuits, which are a subclass of quantum circuits that can be efficiently simulated on a classical computer.
+QuantumClifford.jl is a Julia library for simulation of Clifford circuits, which are a subclass of quantum circuits that can be efficiently simulated on a classical computer as stipulated by the Gottesman-Knill theorem[^1]. This theorem states that a quantum computer using only Clifford group gates, measurements of Pauli group operators, and Clifford group operations conditioned on classical bits (including results of previous measurements) can be perfectly simulated in polynomial time on a probabilistic classical computer. The combination of the Clifford group and an appropriate extra gate such as such as a quantum version of the Toffoli gate, etc. generates a set of unitary operations in U(2ⁿ), thus forming a universal set. This implies that quantum computation only surpasses classical computation when it incorporates gates outside the Clifford group.
 
 This library uses the tableaux formalism[^1] with the destabilizer improvements[^2]. Pauli frames are supported for faster repeated simulation of noisy circuits. Various symbolic and algebraic tools for manipulating, converting, and visualizing states and circuits are also implemented. 
 
+## The Need For Tableaux Formalism
+
+Tableaux Formalism, also known as stabilizer formalism, focuses on the evolution of operators rather than states and has proven highly valuable in understanding certain quantum operations. It provides an efficient way to describe a large class of pure and mixed quantum states in `n`-qubit systems.
+
+An `n`-qubit stabilizer state is uniquely determined as the joint eigenvector with eigenvalue `+1` of a set of `n` tensor products of Pauli operators, resulting in a highly compact representation of the quantum state that requires only `Ο(n²)` parameters[^3]. This compact representation holds promise for a deeper understanding of entanglement structures. Despite this simplification, stabilizer states can still exhibit multi-particle entanglement and allow for the violation of local realism[^4]. 
+
+The stabilizer formalism is crucial in the realm of quantum error-correcting codes[^5], where mixed stabilizer states correspond directly to projectors on subspaces defined by stabilizer codes[^1]. Also, specific communication protocols like quantum teleportation utilize states described by their stabilizer. This group structure is robust enough to enable a wide range of quantum effects, even though it does not encompass the full power of quantum computation. Constructing and analyzing networks of quantum gates can be challenging due to the arbitrary states within the large Hilbert space that quantum computers handle. However, a subset of these networks can be more easily described by tracking the evolution of operators acting on the computer, similar to the Heisenberg representation in quantum mechanics where operators evolve over time.
+
+<div class="mermaid">
+mindmap
+  root((Applications of Stabilizer Formalism))
+    Quantum Error Correction
+      Quantum Error Correcting Codes
+      Fault-Tolerant Quantum Computing
+    Measurement-Based Quantum Computation
+      Cluster States
+      Graph States
+    Quantum Communication
+      Quantum Cryptography
+      Quantum Networking
+    Entanglement Distillation
+    Quantum Metrology
+    Quantum Simulation
+      Stabilizer Circuits
+      Efficient Simulation of Quantum Systems
+</div>
+
 [^1]: [gottesman1998heisenberg](@cite)
 
 [^2]: [aaronson2004improved](@cite)
 
+[^3]: [audenaert2005entanglement](@cite)
+
+[^4]: [guhne2005bell](@cite)
+
+[^5]: [gottesman1997stabilizer](@cite)
+
 The library consists of two main parts: Tools for working with the algebra of Stabilizer Tableaux and tools specifically for efficient Circuit Simulation.
 
 ## Stabilizer Tableau Algebra

docs/src/mixed.md

@@ -15,6 +15,12 @@ Mixed stabilizer states are implemented with [`MixedStabilizer`](@ref) and
 for most tasks as it is much faster by virtue of tracking the destabilizer
 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
+rank deficiency.
+
 ```jldoctest mix
 julia> s = S"XXX
              IZZ";
@@ -59,6 +65,163 @@ julia> logicalzview(m)
 + 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.
+
+```jldoctest mix
+julia> MixedDestabilizer(T"ZI IX XX ZZ", 2)
+𝒟ℯ𝓈𝓉𝒶𝒷
++ Z_
++ _X
+𝒮𝓉𝒶𝒷
++ XX
++ ZZ
+```
+
+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_
++ _X
+𝒮𝓉𝒶𝒷
++ XX
++ 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.
+
+```jldoctest mix
+julia> s = S"-XXX
+             +ZZX
+             +III";
+
+julia> MixedDestabilizer(s, undoperm=false, reportperm=false)
+𝒟ℯ𝓈𝓉𝒶𝒷
++ Z__
++ _Z_
+𝒳ₗ━━━
++ ZZX
+𝒮𝓉𝒶𝒷━
++ Y_Y
++ ZXZ
+𝒵ₗ━━━
++ 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.
+
+```jldoctest mix
+julia> MixedDestabilizer(s, undoperm=true, reportperm=false)
+𝒟ℯ𝓈𝓉𝒶𝒷
++ Z__
++ __Z
+𝒳ₗ━━━
++ ZXZ
+𝒮𝓉𝒶𝒷━
++ YY_
++ ZZX
+𝒵ₗ━━━
++ ZZ_
+```
+
+When `undoperm` is set to `true`, the column permutations performed
+during canonicalizationare automatically reversed before finalizing
+the `MixedDestabilizer`.
+
+```jldoctest mix
+julia> MixedDestabilizer(canonicalize!(s))
+𝒟ℯ𝓈𝓉𝒶𝒷
++ Z__
++ __Z
+𝒳ₗ━━━
++ ZXZ
+𝒮𝓉𝒶𝒷━
++ YY_
++ ZZX
+𝒵ₗ━━━
++ 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.
+
+```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)
+𝒟ℯ𝓈𝓉𝒶𝒷
++ Z_
++ _X
+𝒮𝓉𝒶𝒷
++ XX
++ YZ
+```
+
+# 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.
+
+```jldoctest mix
+julia> s = S"-XXX
+             -ZZI
+             +IZZ";
+
+julia> MixedStabilizer(s)
+- XXX
+- Z_Z
++ _ZZ
+
+julia> MixedStabilizer(s, 2)
+- XXX
+- 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.
+
+```jldoctest mix
+julia> MixedStabilizer(S"-XXX -ZIZ IZZ")
+- XXX
+- Z_Z
++ _ZZ
+
+julia> MixedStabilizer(S"-XXX -ZIZ IZZ", 2)
+- XXX
+- Z_Z
+```
+
+- 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> MixedStabilizer(Tableau(Bool[1 1 1; 0 0 0; 0 0 0],
+                               Bool[0 0 0; 1 0 1; 0 1 1]), 3)
++ XXX
++ Z_Z
++ _ZZ
+```
+
 # Gottesman Canonicalization
 
 To obtain the logical operators we perform a different type of canonicalization,

docs/src/references.bib

@@ -120,6 +120,17 @@ @article{hein2006entanglement
   year={2006}
 }
 
+@article{guhne2005bell,
+  title={Bell inequalities for graph states},
+  author={G{\"u}hne, Otfried and T{\'o}th, G{\'e}za and Hyllus, Philipp and Briegel, Hans J},
+  journal={Physical review letters},
+  volume={95},
+  number={12},
+  pages={120405},
+  year={2005},
+  publisher={APS}
+}
+
 @article{wilde2009logical,
   title={Logical operators of quantum codes},
   author={Wilde, Mark M},