diff --git a/docs/make.jl b/docs/make.jl index 6784b644..3c9dc884 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -11,6 +11,7 @@ Documenter.makedocs(; highlightsig = true, sitename = "Coding Theory Documentation", expandfirst = [], + warnonly = [:missing_docs], pages = ["Introduction" => "index.md", "Tutorials" => [ "Tutorials/Linear Codes.md", diff --git a/docs/src/Classical/cyclic_code.md b/docs/src/Classical/cyclic_code.md index 6de619e7..8ec136b8 100644 --- a/docs/src/Classical/cyclic_code.md +++ b/docs/src/Classical/cyclic_code.md @@ -82,10 +82,6 @@ qcosets qcosets_reps ``` -```@docs -defining_set -``` - ```@docs zeros ``` diff --git a/docs/src/Classical/linear_code.md b/docs/src/Classical/linear_code.md index e2bbf942..a870ab3b 100644 --- a/docs/src/Classical/linear_code.md +++ b/docs/src/Classical/linear_code.md @@ -31,6 +31,8 @@ cardinality rate ``` +See also: encode` + If the linear code was created by passing in a generator (parity-check) matrix, then this matrix is stored in addition to the standard form. Note that this matrix is potentially over complete (has more rows than its rank). The standard form is returned when the optional parameter `stand_form` is set to true. Some code families are not constructed using these matrices. In these cases, the matrices are initially `missing` and are computed and cached when these functions are called for the first time. Direct access to the underlying structs is not recommended. ```@docs generator_matrix @@ -50,9 +52,6 @@ standard_form_permutation ``` The minimum distance of some code families are known and are set during construction. The minimum distance is automatically computed in the constructor for codes which are deemed "small enough". Otherwise, the minimum distance is `missing`. Primitive bounds on the minimum distance are given by -```@docs -minimum_distance_lower_bound -``` ```@docs minimum_distance_upper_bound @@ -81,24 +80,18 @@ The minimum distance and its bounds may be manually set as well. Nothing is done set_distance_lower_bound! ``` -```@docs -set_distance_upper_bound! -``` - ```@docs set_minimum_distance! ``` +See: `minimum_distance_lower_bound`, `set_distance_upper_bound!` + ## Methods ```@docs Singleton_bound ``` -```@docs -encode -``` - ```@docs syndrome ``` diff --git a/docs/src/Classical/new_codes_from_old.md b/docs/src/Classical/new_codes_from_old.md index a67f83bd..bf4661c5 100644 --- a/docs/src/Classical/new_codes_from_old.md +++ b/docs/src/Classical/new_codes_from_old.md @@ -22,19 +22,18 @@ construction_X3 ``` The direct sum code has generator matrix `G1 ⊕ G2` and parity-check matrix `H1 ⊕ H2`. + ```@docs -CodingTheory.⊕ +⊕ ``` The generator matrix of the (direct) product code is the kronecker product of the generator matrices of the inputs. + ```@docs -CodingTheory.× +× ``` The parity-check matrix of the tensor product code is the kronecker product of the parity-check matrices of the inputs. -```@docs -CodingTheory.⊗ -``` There is some debate on how to define this product. This is known to often be the full ambient space. ```@docs @@ -42,7 +41,7 @@ entrywise_product_code ``` ```@docs -CodingTheory./ +/ ``` `juxtaposition` is representation dependent and therefore works on the potentially over-complete generator matrices, not on the standard form. @@ -52,10 +51,7 @@ juxtaposition ## Methods -If `C` is a quasi-cyclic code, `permute_code` returns a `LinearCode` object. -```@docs -permute_code -``` +If `C` is a quasi-cyclic code, `permute_code` returns a `LinearCode` object. See: `permute_code` The most common way to extend a code is to add an extra column to the generator matrix whose values make the sum of the rows zero. This is called an even extension and is the default for `extend(C)`. Alternatively, this new column may be inserted at any index `c` in the matrix, e.g. `extend(C, c)`. In the most general case, one may provide a vector `a` and define the values of the new column to be `-a` dot the row. The standard definition is clearly just the special case that `a` is the all-ones vector. ```@docs diff --git a/docs/src/LDPC/analysis.md b/docs/src/LDPC/analysis.md index 7861be8a..cc203a18 100644 --- a/docs/src/LDPC/analysis.md +++ b/docs/src/LDPC/analysis.md @@ -27,14 +27,8 @@ optimal_threshold density_evolution ``` -```@docs -plot_EXIT_chart -``` # Misc -```@docs -multiplicative_gap -``` ```@docs multiplicative_gap_lower_bound @@ -44,6 +38,8 @@ multiplicative_gap_lower_bound density_lower_bound ``` +See also: `plot_EXIT_chart`, `multiplicative_gap` + ## Comments (these are just temporary notes) diff --git a/docs/src/LDPC/codes.md b/docs/src/LDPC/codes.md index da26e09c..165f9515 100644 --- a/docs/src/LDPC/codes.md +++ b/docs/src/LDPC/codes.md @@ -31,14 +31,7 @@ Parity-check matrix: 6 × 9 1 1 0 0 0 0 1 1 1 ``` -Random regular LDPC codes maybe be constructed via -```@docs -regular_LDPC_code -``` -and irregular LDPC codes via -```@docs -irregular_LDPC_code -``` +Random regular LDPC codes maybe be constructed via `regular_LDPC_code` and `irregular_LDPC_code` ## Attributes The polynomials ``\lambda(x)`` and ``\rho(x)`` as well as the degrees of each variable and check nodes are computed upon construction. @@ -116,33 +109,8 @@ To count or explicitly enumerate the short cycles of the Tanner graph, use count_short_cycles ``` -```@docs -shortest_cycles -``` - -Various information about the ACE values of cycles in the Tanner graph may be computed with the following functions. -```@docs -ACE_spectrum -``` - -```@docs -shortest_cycle_ACE -``` +See also: `shortest_cycles` -```@docs -ACE_distribution -``` - -```@docs -average_ACE_distribution -``` - -```@docs -median_ACE_distribution -``` - -```@docs -mode_ACE_distribution -``` +Various information about the ACE value of cycles in the Tanner graph may be computed with the following functions. See: `ACE_spectrum`, `shortest_cycle_ACE`, `ACE_distribution`, `average_ACE_distribution`, `median_ACE_distribution`, `mode_ACE_distribution` ## Greedy Construction Algorithms diff --git a/docs/src/LDPC/decoders.md b/docs/src/LDPC/decoders.md index 8accc978..0cdc31a0 100644 --- a/docs/src/LDPC/decoders.md +++ b/docs/src/LDPC/decoders.md @@ -21,9 +21,7 @@ sum_product_box_plus min_sum ``` -```@docs -find_MP_schedule -``` +See also: `find_MP_schedule` ## Linear Programming @@ -33,6 +31,4 @@ LP_decoder_LDPC ## Simulations -```@docs -decoder_simulation -``` +See: `decoder_simulation` \ No newline at end of file diff --git a/docs/src/Quantum/product_codes.md b/docs/src/Quantum/product_codes.md index d7447bed..cf1ae930 100644 --- a/docs/src/Quantum/product_codes.md +++ b/docs/src/Quantum/product_codes.md @@ -1,9 +1,9 @@ # Product Codes -- Hypergraph product: [tillich2009quantum](@cite) -- Generalized Shor: [bacon2006quantum](@cite) +- [Hypergraph product](https://errorcorrectionzoo.org/c/hypergraph_product): [Tillich_2014](@cite) +- [Generalized Shor](https://errorcorrectionzoo.org/c/generalized_shor): [bacon2006quantum](@cite) - Hyperbicycle: [pryadko2013quantum](@cite) -- Generealized bicycle: [pryadko2013quantum](@cite), [kovalev2013quantum](@cite), [kovalev1212quantum](@cite), [panteleev2021degenerate](@cite) +- [Generealized bicycle](https://errorcorrectionzoo.org/c/generalized_bicycle): [pryadko2013quantum](@cite), [Kovalev_2013](@cite), [panteleev2021degenerate](@cite) - Generalized hypergraph product: [panteleev2021degenerate](@cite) - Bias-tailored lifted product: [roffe2023bias](@cite) diff --git a/docs/src/Tutorials/Message Passing.md b/docs/src/Tutorials/Message Passing.md index 611ebc91..fde246c8 100644 --- a/docs/src/Tutorials/Message Passing.md +++ b/docs/src/Tutorials/Message Passing.md @@ -247,7 +247,6 @@ lines!(ax, x, x, color = :black) f ``` -![phi](./../assets/images/phi.png) Trying to plot this function with the $\tanh$ versus plotting this function with the exponentials makes the numerical instability of the $\tanh$ apparent. Fortunately, the exponential form makes it apparent that it is not only symmetric about $y = x$, but also that the function is dominated by smaller values of $x$: @@ -406,7 +405,7 @@ julia> Gallager_B(H, y) ``` ## Decimation -Decimation was previously used in message-passing applications outside of error correction and was applied to stabilizer codes in [](@cite). The idea is to freeze the value of a variable node. We can either do this from the start to obtain a so-called *genie-aided* decoder, or we can periodically pause message passing to fix a bit. In *guided decimation*, we pause every fixed number of rounds and freeze the value of the variable node with the highest log-likelihood ratio. In *automated decimation*, we pause after every iteration and fix any bit whose absolute value has passed a certain threshold. +Decimation was previously used in message-passing applications outside of error correction and was applied to stabilizer codes [yao2024belief](@cite). The idea is to freeze the value of a variable node. We can either do this from the start to obtain a so-called *genie-aided* decoder, or we can periodically pause message passing to fix a bit. In *guided decimation*, we pause every fixed number of rounds and freeze the value of the variable node with the highest log-likelihood ratio. In *automated decimation*, we pause after every iteration and fix any bit whose absolute value has passed a certain threshold. It is important to note that when a variable node is fixed to a specific value, the decoder is now sampling possible solutions with that fixed bit, which is different from the ML and MAP problems above. Furthermore, if there is a unique solution and a bit is fixed which does not match the solution, the decoder will fail instead of correcting that bit. For example, fixing the most reliable bit in guided decimation may mean fixing a bit which is still far from reliable and could go either way. On the other hand, fixing a bit could help the decoder converge faster and also break out of trapping sets. In this sense, decimation can be very helpful decoding degenerate stabilizer codes where there are many valid solutions and BP has a difficult time picking one to converge to. @@ -751,7 +750,6 @@ lines!(noise, FER, color = :red) scatter!(noise, FER, color = :red) current_figure() ``` -![CSS_FER_test](./../assets/images/CSS_FER_test.png) TODO REDO THIS FUNCTION @@ -772,7 +770,6 @@ ax2 = Axis(fig2[1, 2], xlabel = "Iteration Number", ylabel = "Number Of Times Co barplot!(ax1, collect(keys(X_iters_15)), X_values, bar_width = 1) barplot!(ax2, collect(keys(Z_iters_15)), Z_values, bar_width = 1) ``` -![CSS_test_iters](./../assets/images/CSS_test_iters.png) The overwhelming majority of convergeneces, for both $X$ and $Z$, occurred within one or two iterations. This is plausible for a couple of reasons. First, note that all variable nodes have degree four but all check nodes have degree nine! This is large for an LDPC code. For low error rates when errors are sparsely distributed over 254 qubits, it may be common that a single check node does not connect to more than one inncorrect variable node and the degrees are high enough to immediately flip any bit. @@ -805,8 +802,6 @@ false Rerunning the simulation without using Bayes' Theorem returns almost symmetric $X$ and $Z$ iteration counts. For completeness, we include both runs on a single plot. The first blue point on the left is due to a single convergence error and the spike on the left further shows that direct sampling is either not appropriate for this error rate or it has not been sampled enough times for accuracy. -![CSS_FER_Bayes_test](./../assets/images/CSS_FER_Bayes_test.png) - ## Example 2: Single-Shot Decoding With Metachecks Next we're going to look at two single-shot decoding schemes. We will call the paper [quintavalle2021single](@cite) scheme one and [higgott2023improved](@cite) scheme two. We encourage the reader to check out both papers directly for details. Briefly, both schemes will consider data errors, as in the previous example, plus additional measurement errors (on the syndrome values). The code family we will look at has an extra matrix, $M$, with the property that $Ms = 0$ for any valid syndrome $s$ of the code. Then assuming that the measurement error $s_e$ didn't take us from a valid syndrome to another valid syndrome, $M(s + s_e) = Ms_e \neq 0$. Whether or not this happens depends on the properties of the classical code with $M$ as its parity-check matrix. To correct the syndrome, we decode using the Tanner graph based on $M$. Then we will use the corrected syndrome to decode the stabilizers. @@ -1220,14 +1215,13 @@ julia> check_weights(X_meta_L) By distance eight, scheme one was difficult to run without a cluster. We did not attempt distance nine with this scheme. This is problematic for many reasons, the most important of which is that many code families do not "settle in" to their asymptotic behaviors until distances much higher than this (although the exact distance depends on the decoder being used). For example, for the surface codes under minimum-weight perfect-matching (MWPM), anything below distance 20 is considered the small-code regime (compare this to distance seven for the same code family using trellis decoding). -![CSS_Single_Shot_test](./../assets/images/CSS_Single_Shot_test.png) - Logical errors were equally distributed among the cosets and only occurred on odd-distance codes. + julia> x = -20:.05:20; y = [abs(atanh(tanh(x)) - x) for x in x]; y2 = [exp(2abs(x)) / 2^56 for x in x]; plot(x, [replace(y, 0.0 => 1e-21) y2], ylims = (1e-20, 1), yscale = :log10, linewidth = 0.5, label = ["abs(atanh(tanh(x)) - x)" "exp(2abs(x)) / 2^56"]) p = 1 - 1/(1 + exp(LLR)) if LLR = log(p / (1 - p)) diff --git a/docs/src/references.bib b/docs/src/references.bib index a06832bc..6eeb9ced 100644 --- a/docs/src/references.bib +++ b/docs/src/references.bib @@ -7,16 +7,13 @@ @misc{hastings2021quantum } @misc{hastings2016, - archiveprefix = {arxiv}, - author = {Hastings, M. B.}, - eprint = {1611.03790}, - keywords = {Quantum Physics}, - month = nov, - number = {arXiv:1611.03790}, - publisher = {{arXiv}}, - title = {Weight Reduction for Quantum Codes}, - urldate = {2023-11-14}, - year = {2016} + title={Weight Reduction for Quantum Codes}, + author={M. B. Hastings}, + year={2016}, + eprint={1611.03790}, + archivePrefix={arXiv}, + primaryClass={quant-ph}, + url={https://arxiv.org/abs/1611.03790}, } @inproceedings{hastings2021fiber, @@ -121,10 +118,18 @@ @article{bacon2006quantum year={2006} } -@inproceedings{tillich2009quantum, - title={Quantum LDPC codes with positive rate and minimum distance proportional to n $1/2$}, - author={Tillich, J-P and Zemor, G}, - booktitle={2009 IEEE International Symposium on Information Theory} +@article{Tillich_2014, + title={Quantum LDPC Codes With Positive Rate and Minimum Distance Proportional to the Square Root of the Blocklength}, + volume={60}, + ISSN={1557-9654}, + url={http://dx.doi.org/10.1109/TIT.2013.2292061}, + DOI={10.1109/tit.2013.2292061}, + number={2}, + journal={IEEE Transactions on Information Theory}, + publisher={Institute of Electrical and Electronics Engineers (IEEE)}, + author={Tillich, Jean-Pierre and Zemor, Gilles}, + year={2014}, + month=feb, pages={1193–1202} } @inproceedings{pryadko2013quantum, @@ -136,22 +141,18 @@ @inproceedings{pryadko2013quantum year={2013} } -@article{kovalev2013quantum, - title={Quantum Kronecker sum-product low-density parity-check codes with finite rate}, - author={Kovalev, Alexey A and Pryadko, Leonid P}, - journal={Physical Review A—Atomic, Molecular, and Optical Physics}, - volume={88}, - number={1}, - pages={012311}, - year={2013}, - publisher={APS} -} - -@article{kovalev1212quantum, - title={Quantum “hyperbicycle” low density parity check codes with finite rate}, - author={Kovalev, AA and Pryadko, LP}, - journal={arXiv}, - volume={1212} +@article{Kovalev_2013, + title={Quantum Kronecker sum-product low-density parity-check codes with finite rate}, + volume={88}, + ISSN={1094-1622}, + url={http://dx.doi.org/10.1103/PhysRevA.88.012311}, + DOI={10.1103/physreva.88.012311}, + number={1}, + journal={Physical Review A}, + publisher={American Physical Society (APS)}, + author={Kovalev, Alexey A. and Pryadko, Leonid P.}, + year={2013}, + month=jul } @article{panteleev2021degenerate, @@ -173,3 +174,12 @@ @article{roffe2023bias year={2023}, publisher={Verein zur F{\"o}rderung des Open Access Publizierens in den Quantenwissenschaften} } + +@inproceedings{yao2024belief, + title={Belief propagation decoding of quantum LDPC codes with guided decimation}, + author={Yao, Hanwen and Laban, Waleed Abu and H{\"a}ger, Christian and i Amat, Alexandre Graell and Pfister, Henry D}, + booktitle={2024 IEEE International Symposium on Information Theory (ISIT)}, + pages={2478--2483}, + year={2024}, + organization={IEEE} +} diff --git a/src/Classical/cyclic_code.jl b/src/Classical/cyclic_code.jl index e2b08dfe..83ad777e 100644 --- a/src/Classical/cyclic_code.jl +++ b/src/Classical/cyclic_code.jl @@ -433,11 +433,7 @@ Return the set of representatives for the q-cyclotomic cosets of the cyclic code """ qcosets_reps(C::AbstractCyclicCode) = C.qcosets_reps -""" - defining_set(C::AbstractCyclicCode) -Return the defining set of the cyclic code. -""" defining_set(C::AbstractCyclicCode) = C.def_set """