Improving Documentation and adding references - adding section on Minimum distance algorithms for Quantum Stabilizer Codes

[Fe-r-oz]

Hi, Eric!

It seems that the documentation can be significantly improved. At some places, there is too much detail which can be made shorter. For example, the Background section is too long. It can be made shorter so that users can directly jump on the codes. The same can be seen with the background of cyclic codes.. However, Quantum Codes maintain a nice balance between details. I think the background covers most of the pedagogical details that the user is expected to know, we can always refer to the Error Correcting Books, such as MacWilliams Book or Huffman book in the reference section. In the documentation, we can cover the points that are most needed. Also, documentation about Stabilizer Subsystem codes needs to be added as well. At the moment, there is no clear representation of the different types of StabilizerCode representation that are present.

Organization and depiction could be improved as well. Perhaps using Mermaid Charts to give a description of all the ECCs. The good thing about these charts is they are written in html code that can be added in the docstring, so they can be easily updated when new functionality is added. Please checkout the following demos based on the current codes from documentation:

mindmap
  root((Product codes))
    Hypergraph
    Generalized Shor
    Hyperbicycle
    Generalized bicycle
    Generalized hypergraph
    Bias-tailored lifted product

mindmap
  root((Classical Codes))
    Linear Codes
    Concatenated Codes
    Cyclic Codes
       BCH
       Reed-Solomon
    Quasi-Cyclic Codes
    Generalized Reed-Solomon Codes
    Reed-Muller Codes
    Modifying Codes
    Product Codes
    Miscellaneous Known Linear Codes

mindmap
  root((LDPC Codes))
    LDPC Codes
   Tanner Codes
   LDPC Ensemble Analysis
   LDPC Noise Channels
   Decoding LDPC Codes

Also, it seems that the references to all sorts of quantum and classical codes are provided in text. It should be added in the references.bib as well so that it can appear in References section. I think this needs to be removed: https://esabo.github.io/CodingTheory/dev/#TEST,-DELETE-THIS. In addition, Developer Documentation link is broken. Also, the Introduction says, welcome to ErrorCorrection.jl.

In addition, more references have to be added such as your PhD Dissertation Trellis Decoding And Applications For Quantum Error Correction which goes in great detail about minimum distance algorithms. I am going through your PhD dissertation and would be delighted to add documentation of minimum distance algorithms. I think the minimum distance algorithm is in the dev phase so that's why there is less documentation about it.

Let me know what you think. Thank you for your feedback!

[esabo]

There's a lot of separate issues and comments here so I'll try to go through them one-by-one.

First, the documentation we have as a whole is terrible solely because it takes a long time to write well (and my company wants other features first) and I haven't gotten around to it yet on my own time (I blame the baby here). Second, it no longer compiles when I updated Documenter.jl, so it's missing all updates coming from the dev branch. I started on classical codes, never got to quantum codes. I think what's there is a mere shell of what needs to be there and came about by simply copying and pasting tests. So I absolutely agree this is a priority if other people are going to use it.

As for the level of detail, I think having too much is better than having too little. The main goal in what's written so far is to establish notation. The notation used in M&S differs from that of H&P differs from that of (etc). Even standard terminology such as narrow-sense is defined differently throughout the literature. So I decided to clearly specify how I am using the terms. Other parts, such as the expanded codes, don't have good references, so I decided to write my own for the community, like a blog post.

I've never seen Mermaid charts; they seem useful. The problem with type diagrams is the lack of inheritance. I have opted to implement this with traits instead. At one point this diagram was on the documentation, TypeHierarchy.pdf but it confused people because no type can have multiple super types in Julia and the diagram is therefore conceptual. So I removed it. Something should replace it though.

That test section was pushed by someone else and I have long deleted it but can't compile the docs.

There is no developer documentation page yet haha. No one outside my work slack channel is really developing it so I never got around to it. If you want to work on the package, we can sort this out.

[esabo]

Oh, and there is already a package called CodingTheory.jl in the package repo, so the name for this package is slowly being changed to ErrorCorrection.jl or something similar.

[Fe-r-oz]

Thank you for your insightful comments. I will be happy to work on these issues and improve the documentation after the dev branch gets merged.