More documentation on the various ways to construct Stab/Destab/MixedDestab objects

[Krastanov]

A friend asked me over email something that should probably be added to the documentation (after being polished)

A quick question, in quantumclifford.jl, how should I manually construct the (Mixed)Destabilizer tableau? Suppose I have a list of stabilizers and destabilizers as strings, for example s = ["XX","ZZ"] and d=["ZI","IX"].

My answer was

[Fe-r-oz]

I will be delighted to work in this issue!

[Krastanov]

That would be great! It is a pretty difficult balance to strike between too much information on a given page and too many separate pages -- this will need some pedagogical effort, maybe a separate page, maybe a lot of reference to that new page, maybe something else

[Fe-r-oz]

Indeed, I understand your point. Striking balance is important so that the reader is not overwhelmed by too much information in one page. I will give proper attention to it.

[Fe-r-oz]

On the page about choosing Data Structure, https://quantumsavory.github.io/QuantumClifford.jl/stable/datastructures/#Choosing-Appropriate-Data-Structure

Would you like to add a flowchart like this? I can modify it as per your requirements if needed.

[Fe-r-oz]

Another Representation:

[Krastanov]

These look promising! Are you using mermaid for them? I would prefer to keep the source for diagrams as part of the documentation, so that it is easy to modify. We already do something like that for QuantumSavory: https://quantumsavory.github.io/QuantumSavory.jl/stable/register_interface/

Using mermaid can also help with making the visualization a bit tighter -- there is a lot of empty space in this one.

I would suggest doing first the separation between (Mixed)Stabilizer and (Mixed)Destabilizer and only then dealing with the mixed-vs-nonmixed distinction.

MixedDestabilizer is probably the main and most useful datastructure, but it is not included here.

I think all of these datastructures support projective measurements, definitely including Stabilizer.

Some of the descriptions inside of the bottom rectangles does not make much sense to me right now -- "handles commuting operators" and "requires user to check for consistency" and "no canonicalization needed".

Explicit descriptions of what these datastructures are would be useful.

[Fe-r-oz]

Yes, Mermaid!

Thanks for your comments! Please let me know your further comments.

Color Scheme 1:

Color Scheme 2:

Color Scheme 3:

Stabilizer: Requires user to check for consistency. This summarizes ""It does not enforce requirements for pure stabilizer state (the rows of the tableau do not necessarily commute, nor are they forced to be Hermitian; the tableau might be under determined, redundant, or contradictory). It is up to the user to ensure that the initial values in the tableau are meaningful and consistent.""

MixedDestabilizer: handles commuting operators -- this summarizes that " efficiently handling projections onto commuting operators that are not explicitly represented in the stabilizer".
--Improved this as Project! on non-Stabilizer commuting operators

Destabilizer: no canonicalization needed -- This summarizes ""project! called on it never requires a stabilizer canonicalization"".
-- Improved it as no stabilizer canonicalization needed

"If you will never need projective measurements you probably would want to use Stabilizer. Also, canonicalize!, project!, and generate! can accept an under determined (mixed state) Stabilizer instance and operate correctly. canonicalize! can also accept a redundant Stabilizer (i.e. not all rows are independent), leaving as many identity rows at the bottom of the canonicalized tableau as the number of redundant stabilizers in the initial tableau.""

[Fe-r-oz]

Smaller size of decision boxes:

Solarized Dark Scheme:

[Fe-r-oz]

Minor Cleanup since all data structures support projective measurements:

1:

2:

3:

[Fe-r-oz]

From the Gottesman and Aaronson paper[2], we can add a flowchart of generalization of the stabilizer states as well. Please suggest improvement here as well. Thanks!

[Fe-r-oz]

Another set of options:

1:

2:

[Fe-r-oz]

To be consistent with other member packages, I think it's better to use the default scheme instead of the ones presented.