From 965e605cd71f03b199a0ed16a7c62e656bfd11e6 Mon Sep 17 00:00:00 2001 From: Leonid Pryadko Date: Fri, 12 Jan 2024 08:20:03 -0800 Subject: [PATCH 1/5] Ensure all functions are documented properly --- PackageInfo.g | 4 ++-- lib/qdistrnd.g | 55 +++++++++++++++++++++++++++++----------------- tst/qdistrnd02.tst | 4 ++-- 3 files changed, 39 insertions(+), 24 deletions(-) diff --git a/PackageInfo.g b/PackageInfo.g index ccaaed4..26e0726 100644 --- a/PackageInfo.g +++ b/PackageInfo.g @@ -16,8 +16,8 @@ SetPackageInfo( rec( PackageName := "QDistRnd", Subtitle := "Calculate the distance of a q-ary quantum stabilizer code", - Version := "0.8.7", - Date := "20/12/2023", + Version := "0.8.8", + Date := "12/01/2024", License := "GPL-2.0-or-later", PackageWWWHome := "https://QEC-pages.github.io/QDistRnd", SourceRepository := diff --git a/lib/qdistrnd.g b/lib/qdistrnd.g index 481484a..2052802 100644 --- a/lib/qdistrnd.g +++ b/lib/qdistrnd.g @@ -11,10 +11,12 @@ #! @Chapter AllFunctions #! @Section HelperFunctions -#! @Description Calculate the average of the components of a `vector` -#! containing numbers + + +#! @Description Calculate the average of the components of a numerical `vector` #! @Arguments vector -BindGlobal("QDR_AverageCalc", +DeclareGlobalFunction("QDR_AverageCalc"); +InstallGlobalFunction("QDR_AverageCalc", function(mult) return 1.0*Sum(mult)/Length(mult); end @@ -32,14 +34,16 @@ BindGlobal("QDR_AverageCalc", #! **Note: the parity of vector `length` and the format are not verified!!!** #! @Returns symplectic weight of a vector #! @Arguments vector, field -BindGlobal("QDR_SymplVecWeight", +DeclareGlobalFunction("QDR_SymplVecWeight"); +InstallGlobalFunction("QDR_SymplVecWeight", function(vec, F) - local wgt, i, len; # local variables: wgt - the weight, i - for "for" loop, len - length of vec + local wgt, i, len; + # local variables: wgt - the weight, i - for "for" loop, len - length of vec len := Length(vec); -# if (not IsInt(len / 2)) then -# Error(" symplectic vector must have even length, = ", len,"\n"); -# fi; + # if (not IsInt(len / 2)) then + # Error(" symplectic vector must have even length, = ", len,"\n"); + # fi; wgt := 0; for i in [1..(len/2)] do @@ -54,7 +58,9 @@ BindGlobal("QDR_SymplVecWeight", #! @Description count the total number of non-zero entries in a matrix. #! @Arguments matrix -BindGlobal("QDR_WeightMat", +#! @Returns number of non-zero elements +DeclareGlobalFunction("QDR_WeightMat"); +InstallGlobalFunction("QDR_WeightMat", function(mat) local NonZeroElem,i,rows; rows:=DimensionsMat(mat)[1]; @@ -74,7 +80,9 @@ BindGlobal("QDR_WeightMat", #! program. See for #! related discussion. #! @Arguments vector, n, num -BindGlobal("QDR_DoProbOut", +#! @Returns nothing +DeclareGlobalFunction("QDR_DoProbOut"); +InstallGlobalFunction("QDR_DoProbOut", function(mult,n,num) local s0,s1,s2; Print("=", QDR_AverageCalc(mult)); @@ -83,9 +91,9 @@ BindGlobal("QDR_DoProbOut", s1:=Sum(mult); s2:=Sum(mult, x->x^2); Print(" X^2_",s0-1,"=",Float(s2*s0-s1^2)/s1, "\n"); -# Here the expression is due to the map to -# multinomial distribution (divide by the total) and the quantity is -# supposed to be distributed by chi^2 with s0-1 degrees of freedom. + # Here the expression is due to the map to + # multinomial distribution (divide by the total) and the quantity is + # supposed to be distributed by chi^2 with s0-1 degrees of freedom. else Print("\n"); fi; @@ -102,7 +110,8 @@ BindGlobal("QDR_DoProbOut", #! See Chapter for details. #! @Returns the created header string #! @Arguments F -BindGlobal("QDR_FieldHeaderStr", +DeclareGlobalFunction("QDR_FieldHeaderStr"); +InstallGlobalFunction("QDR_FieldHeaderStr", function(F) # field F local p,m, poly,lis,i,j, b, str, out; if not IsField(F) then @@ -191,7 +200,8 @@ BindGlobal("QDR_FieldHeaderStr", #! @Returns the list [Field, ConversionDegree, FormatIndex] (plus anything else we #! may need in the future); the list is to be used as the second #! parameter in `QDR_ProcEntry()` -BindGlobal("QDR_ProcessFieldHeader", +DeclareGlobalFunction("QDR_ProcessFieldHeader"); +InstallGlobalFunction("QDR_ProcessFieldHeader", function(recs,optF) local m,F,Fp,poly,x,ic,is,a,x_global_val, x_bound,x_readonly; @@ -309,7 +319,8 @@ BindGlobal("QDR_ProcessFieldHeader", #! #! @Returns the converted field element #! @Arguments str, fmt, FileName, LineNo -BindGlobal("QDR_ProcEntry", +DeclareGlobalFunction("QDR_ProcEntry"); +InstallGlobalFunction("QDR_ProcEntry", function(str,fmt,FileName,LineNo) local ival, fval; ival:=Int(str); @@ -398,7 +409,8 @@ BindGlobal("QDR_ProcEntry", #! of the group are represented depending on whether the field is a prime #! field ($ q $ a prime) or an extension field with $ q=p^m $, $p$ prime, and $m>1$. #! -BindGlobal("ReadMTXE", +DeclareGlobalFunction("ReadMTXE"); +InstallGlobalFunction("ReadMTXE", function(StrPath, opt... ) # supported option: "field" local input, data, fmt, line, pair, F, rowsG, colsG, G, G1, i, iCommentStart,iComment; @@ -540,7 +552,8 @@ BindGlobal("ReadMTXE", #! of the group are represented depending on whether the field is a prime #! field ($ q $ a prime) or an extension field with $ q=p^m $, $ m>1 $. #! -BindGlobal("WriteMTXE", # function (StrPath,pair,G,comment...) +DeclareGlobalFunction("WriteMTXE"); +InstallGlobalFunction("WriteMTXE", # function (StrPath,pair,G,comment...) function (StrPath,pair,G,comment...) # supported option: field [default: GF(2)] local F, dims, rows, cols, nonzero, i, row, pos, filename; # F - field to be used (default: no field specified) @@ -699,7 +712,8 @@ BindGlobal("WriteMTXE", # function (StrPath,pair,G,comment...) #! The parity of the number of columns is verified. #! @Returns `H` (the check matrix constructed) #! -BindGlobal("QDR_MakeH", +DeclareGlobalFunction("QDR_MakeH"); +InstallGlobalFunction("QDR_MakeH", function(G, F) local dims, i, H; @@ -1103,7 +1117,8 @@ InstallGlobalFunction("DistRandStab", #! constructs the corresponding `m` by 2`n` double circulant matrix #! obtained by `m` repeated cyclic shifts of the coefficients' vector #! by $s=2$ positions at a time. -BindGlobal("QDR_DoCirc", +DeclareGlobalFunction("QDR_DoCirc"); +InstallGlobalFunction("QDR_DoCirc", function(poly,m,n,F) local v,perm,j,deg,mat; v:=CoefficientsOfUnivariatePolynomial(poly); diff --git a/tst/qdistrnd02.tst b/tst/qdistrnd02.tst index a8efe2e..78e5dc4 100644 --- a/tst/qdistrnd02.tst +++ b/tst/qdistrnd02.tst @@ -29,11 +29,11 @@ gap> H:=One(F)*[[1,0, -1,0, 0,0, 0,0 ], # original Hx in odd positions gap> DistRandStab(H,100,0,2 : field:=F); 2 -# doc/_Chapter_AllFunctions.xml:178-181 +# doc/_Chapter_AllFunctions.xml:309-312 gap> QDR_AverageCalc([2,3,4,5]); 3.5 -# doc/_Chapter_AllFunctions.xml:184-195 +# doc/_Chapter_AllFunctions.xml:315-326 gap> F:=GF(3);; gap> x:=Indeterminate(F,"x");; poly:=One(F)*(1-x);; gap> n:=5;; From 4792b76763a748d6f01d0a18c59aa045b46cb6db Mon Sep 17 00:00:00 2001 From: Leonid Pryadko Date: Fri, 12 Jan 2024 08:29:12 -0800 Subject: [PATCH 2/5] moved example programs to examples/ directory --- {lib => examples}/cyclic.g | 0 {lib => examples}/examples.g | 0 2 files changed, 0 insertions(+), 0 deletions(-) rename {lib => examples}/cyclic.g (100%) rename {lib => examples}/examples.g (100%) diff --git a/lib/cyclic.g b/examples/cyclic.g similarity index 100% rename from lib/cyclic.g rename to examples/cyclic.g diff --git a/lib/examples.g b/examples/examples.g similarity index 100% rename from lib/examples.g rename to examples/examples.g From ca4e93714153f1981f33ed1e33db31911c9a21b2 Mon Sep 17 00:00:00 2001 From: Leonid Pryadko Date: Fri, 12 Jan 2024 09:40:02 -0800 Subject: [PATCH 3/5] documentation update --- doc/body.autodoc | 20 ++++++++++---------- doc/{QDistRnd.bib => references.bib} | 0 examples/examples.g | 4 ++-- lib/qdistrnd.g | 4 ++-- makedoc.g | 2 +- tst/qdistrnd02.tst | 10 +++++----- 6 files changed, 20 insertions(+), 20 deletions(-) rename doc/{QDistRnd.bib => references.bib} (100%) diff --git a/doc/body.autodoc b/doc/body.autodoc index cd5fcb0..7f5538e 100644 --- a/doc/body.autodoc +++ b/doc/body.autodoc @@ -131,10 +131,10 @@ obtained as the first row of $G_S$. ). @Subsection CSS version of the algorithm -@SubsectionLabel DistRandCSS +@SubsectionLabel AlgorithmCSS -The described version of the algorithm is implemented in the function -. It applies to the case of +The described version of the algorithm is implemented in the function `DistRandCSS` +(). It applies to the case of Calderbank-Shor-Steane (CSS) codes, where the matrices $P=H_X$ and $Q=H_Z$ are called the CSS generator matrices, and the computed minimum weight is the distance $d_Z$ of the code. The number of @@ -148,7 +148,7 @@ $[[n,k,(d_X,d_Z)]]_q$, or simply $[[n,k,d]]_q$ as for a general $q$-ary stabilizer code. @Subsection Generic version of the algorithm -@SubsectionLabel DistRandStab +@SubsectionLabel AlgorithmGeneric CSS codes are a subclass of general $F$-linear stabilizer codes which are specified by a single stabilizer generator matrix $H=(A|B)$ @@ -171,7 +171,7 @@ generators $H_X$ and $H_Z$, the stabilizer generator matrix has a block-diagonal form, $H=$`diag`$(H_X,H_Z)$. A version of the algorithm for general $F$-linear stabilizer codes is -implemented in the function . +implemented in the function `DistRandStab` (). **Important Notice**: In general, here one could use most general permutations of $2n$ columns, or restricted permutations of $n$ @@ -373,7 +373,7 @@ codewords found (i.e., the average $\langle n\rangle$ must be large, which is the same condition as needed for confidence in the result.) With `debug[4]` set (binary value 8) in `DistRandCSS` and -`DistRandStab` , whenever more +`DistRandStab` (), whenever more than one minimum-weight vector is found, the quantity $X^2$ is computed and output along with the average number of times $\langle n\rangle$ a minimum-weight codeword has been found. However, no @@ -467,7 +467,7 @@ The ordering of the columns is governed by a parameter this case the MTX header should use the `integer` type. This is the defailt storage format for stabilizer generator matrices of CSS codes, and also the internal matrix format for single-block matrices - accepted by the function `DistRandCSS`, see . * With `pair=1` the block matrix $(A,B)$ is stored with intercalated @@ -492,8 +492,8 @@ corresponds to `type=complex`. **It is strongly recommended** that matrices intended for use by others should only use these two variants of the MTXE format. -For efficiency reasons, the function `DistRandStab` assumes the generator matrix with +For efficiency reasons, the function `DistRandStab` () assumes the generator matrix with intercalated columns. @Subsection Explicit format of each line @@ -736,7 +736,7 @@ to use the default binary field]. @EndExample Finally, the following is an example of a five-qudit code over -$\mathop{\rm GF}(2^3)$ constructed by the script `lib/cyclic.g`. +$\mathop{\rm GF}(2^3)$ constructed by the script `examples/cyclic.g`. @BeginCode SampleFileC %%MatrixMarket matrix coordinate complex general % Field: GF(2^3) PrimitiveP(x): x^3+x+1 diff --git a/doc/QDistRnd.bib b/doc/references.bib similarity index 100% rename from doc/QDistRnd.bib rename to doc/references.bib diff --git a/examples/examples.g b/examples/examples.g index 24c7557..d813153 100644 --- a/examples/examples.g +++ b/examples/examples.g @@ -119,7 +119,7 @@ DistRandCSS(GX,GZ,100,1,2:field:=GF(2)); #! @Section Randomly generated cyclic codes #! As a final and hopefully somewhat useful example, the file -#! "lib/cyclic.g" contains a piece of +#! "examples/cyclic.g" contains a piece of #! code searching for random one-generator cyclic codes of length #! $n:=15$ over the field $\mathop{\rm GF}(8)$, and generator weight `wei:=6`. #! Note how the `mindist` parameter and the option `maxav` are used to @@ -132,7 +132,7 @@ DistRandCSS(GX,GZ,100,1,2:field:=GF(2)); #! @Subsection Examples #! Here are a few simple examples illustrating the use of distance -#! functions. In all examples, we use `DistRandCSS` and +#! functions. In all examples, we use functions `DistRandCSS` and #! `DistRandStab` with `debug=2` to ensure that row #! orthogonality in the input matrices is verified. #! @BeginExample diff --git a/lib/qdistrnd.g b/lib/qdistrnd.g index 2052802..411ba69 100644 --- a/lib/qdistrnd.g +++ b/lib/qdistrnd.g @@ -899,13 +899,13 @@ InstallGlobalFunction("DistRandCSS", #! Computes an upper bound on the distance $d$ of the #! $F$-linear stabilizer code with generator matrix $G$ whose rows #! are assumed to be symplectic-orthogonal, see Section (**orthogonality is not verified**). +#! Subsect="Subsection_AlgorithmGeneric"/> (**orthogonality is not verified**). #! #! Details of the input parameters: #! * `G`: the input matrix with elements in the Galois `field` $F$ #! with $2n$ columns $(a_1,b_1,a_2,b_2,\ldots,a_n,b_n)$. #! The remaining options are identical to those in the function -#! `DistRandCSS` . +#! `DistRandCSS` . #! * `num`: number of information sets to construct (should be large) #! * `mindist` - the algorithm stops when distance equal or smaller than `mindist` #! is found - set it to 0 if you want the actual distance diff --git a/makedoc.g b/makedoc.g index 19eeea2..6496f10 100644 --- a/makedoc.g +++ b/makedoc.g @@ -1,7 +1,7 @@ LoadPackage( "AutoDoc" ); AutoDoc( rec( scaffold := true, autodoc := rec( - scan_dirs := [".", "doc", "lib"] + scan_dirs := [".", "doc", "lib", "examples"] ), gapdoc := rec( diff --git a/tst/qdistrnd02.tst b/tst/qdistrnd02.tst index 78e5dc4..7c200d2 100644 --- a/tst/qdistrnd02.tst +++ b/tst/qdistrnd02.tst @@ -10,18 +10,18 @@ # gap> START_TEST( "qdistrnd02.tst"); -# doc/_Chapter_AllFunctions.xml:19-25 +# doc/_Chapter_AllFunctions.xml:125-131 gap> F:=GF(5);; gap> Hx:=One(F)*[[1,-1,0,0 ],[0,0,1,-1]];; gap> Hz:=One(F)*[[1, 1,1,1]];; gap> DistRandCSS(Hz,Hx,100,0,2 : field:=F); 2 -# doc/_Chapter_AllFunctions.xml:32-35 +# doc/_Chapter_AllFunctions.xml:138-141 gap> DistRandCSS(Hz,Hx,100,2,2 : field:=F); -2 -# doc/_Chapter_AllFunctions.xml:42-49 +# doc/_Chapter_AllFunctions.xml:148-155 gap> F:=GF(5);; gap> H:=One(F)*[[1,0, -1,0, 0,0, 0,0 ], # original Hx in odd positions > [0,0, 0,0, 1,0, -1,0 ], @@ -29,11 +29,11 @@ gap> H:=One(F)*[[1,0, -1,0, 0,0, 0,0 ], # original Hx in odd positions gap> DistRandStab(H,100,0,2 : field:=F); 2 -# doc/_Chapter_AllFunctions.xml:309-312 +# doc/_Chapter_AllFunctions.xml:463-466 gap> QDR_AverageCalc([2,3,4,5]); 3.5 -# doc/_Chapter_AllFunctions.xml:315-326 +# doc/_Chapter_AllFunctions.xml:469-480 gap> F:=GF(3);; gap> x:=Indeterminate(F,"x");; poly:=One(F)*(1-x);; gap> n:=5;; From b2145e63071a99fb6beaf76d2420c27fa8506bf5 Mon Sep 17 00:00:00 2001 From: Leonid Pryadko Date: Fri, 12 Jan 2024 09:45:31 -0800 Subject: [PATCH 4/5] bibliography renamed --- doc/{references.bib => QDistRnd.bib} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename doc/{references.bib => QDistRnd.bib} (100%) diff --git a/doc/references.bib b/doc/QDistRnd.bib similarity index 100% rename from doc/references.bib rename to doc/QDistRnd.bib From ceaa4c7732e47c6662de371cfdd795c4c3dc807b Mon Sep 17 00:00:00 2001 From: Leonid Pryadko Date: Fri, 12 Jan 2024 10:01:52 -0800 Subject: [PATCH 5/5] tmp directory is no longer needed --- .gitignore | 4 +++- examples/cyclic.g | 3 ++- examples/examples.g | 7 +++---- tmp/n5_q3_complex.mtx | 23 ----------------------- tst/qdistrnd01.tst | 13 ++++++------- 5 files changed, 14 insertions(+), 36 deletions(-) delete mode 100644 tmp/n5_q3_complex.mtx diff --git a/.gitignore b/.gitignore index ff08017..c1212bd 100644 --- a/.gitignore +++ b/.gitignore @@ -14,6 +14,7 @@ doc/*.css doc/*.js auto/* tmp/* +tmp /doc/*.aux /doc/*.bbl /doc/*.blg @@ -36,4 +37,5 @@ tmp/* /doc/QDistRnd.xml /doc/title.xml /doc/manual.lab -/doc/manual.six \ No newline at end of file +/doc/manual.six +/matrices/n5_q3_complex.mtx \ No newline at end of file diff --git a/examples/cyclic.g b/examples/cyclic.g index 6869ce9..ca6d129 100644 --- a/examples/cyclic.g +++ b/examples/cyclic.g @@ -2,7 +2,8 @@ #! codes of length 15 over $GF(8)$, with stabilizer generators of weight 6, #! by going over 10000 random #! polynomials of each degree from 4 to 15. It takes just a couple minutes on a -#! typical notebook. +#! typical notebook. +AUTODOC_CreateDirIfMissing("tmp");; q:=8;; F:=GF(q);; wei:=6;; x:=Indeterminate(F,"x");; n:=15;; dmax:=0*[1..n]; # record the max degrees for the reference for deg in [wei-1..n-1] do # polynomial degree diff --git a/examples/examples.g b/examples/examples.g index d813153..67a8fff 100644 --- a/examples/examples.g +++ b/examples/examples.g @@ -19,12 +19,11 @@ Display(mat); #! . 2 2 . . . 1 . . 1 d:=DistRandStab(mat,100,1,0 : field:=F,maxav:=20/n); #! 3 -AUTODOC_CreateDirIfMissing("tmp");; -WriteMTXE("tmp/n5_q3_complex.mtx",3,mat, +WriteMTXE("matrices/n5_q3_complex.mtx",3,mat, "% The 5-qubit code [[5,1,3]]_3", "% Generated from h(x)=1+x^3-x^5-x^6", "% Example from the QDistRnd GAP package" : field:=F); -#! File tmp/n5_q3_complex.mtx was created +#! File matrices/n5_q3_complex.mtx was created #! @EndExample #! Here is the contents of the resulting file which also illustrates @@ -66,7 +65,7 @@ WriteMTXE("tmp/n5_q3_complex.mtx",3,mat, #! Notice that a `pair=2` or `pair=3` matrix is always converted to `pair=1`, i.e., with $2n$ #! intercalated columns $(a_1,b_1,a_2,b_2,\ldots)$. #! @BeginExample -lis:=ReadMTXE("tmp/n5_q3_complex.mtx");; +lis:=ReadMTXE("matrices/n5_q3_complex.mtx");; lis[1]; # the field #! GF(3) lis[2]; # converted to `pair=1` diff --git a/tmp/n5_q3_complex.mtx b/tmp/n5_q3_complex.mtx deleted file mode 100644 index 7bf8a8e..0000000 --- a/tmp/n5_q3_complex.mtx +++ /dev/null @@ -1,23 +0,0 @@ -%%MatrixMarket matrix coordinate complex general -% Field: GF(3) -% The 5-qubit code [[5,1,3]]_3 -% Generated from h(x)=1+x^3-x^5-x^6 -% Example from the QDistRnd GAP package -% Values Z(3) are given -4 5 16 -1 1 1 0 -1 2 0 1 -1 3 0 2 -1 4 2 0 -2 2 1 0 -2 3 0 1 -2 4 0 2 -2 5 2 0 -3 1 2 0 -3 3 1 0 -3 4 0 1 -3 5 0 2 -4 1 0 2 -4 2 2 0 -4 4 1 0 -4 5 0 1 diff --git a/tst/qdistrnd01.tst b/tst/qdistrnd01.tst index 07d954a..9b2f5c7 100644 --- a/tst/qdistrnd01.tst +++ b/tst/qdistrnd01.tst @@ -10,7 +10,7 @@ # gap> START_TEST( "qdistrnd01.tst"); -# doc/_Chapter_Examples.xml:20-38 +# doc/_Chapter_Examples.xml:20-37 gap> q:=3;; F:=GF(q);; gap> x:=Indeterminate(F,"x");; poly:=One(F)*(1+x^3-x^5-x^6);; gap> n:=5;; @@ -22,15 +22,14 @@ gap> Display(mat); . 2 2 . . . 1 . . 1 gap> d:=DistRandStab(mat,100,1,0 : field:=F,maxav:=20/n); 3 -gap> AUTODOC_CreateDirIfMissing("tmp");; -gap> WriteMTXE("tmp/n5_q3_complex.mtx",3,mat, +gap> WriteMTXE("matrices/n5_q3_complex.mtx",3,mat, > "% The 5-qubit code [[5,1,3]]_3", > "% Generated from h(x)=1+x^3-x^5-x^6", > "% Example from the QDistRnd GAP package" : field:=F); -File tmp/n5_q3_complex.mtx was created +File matrices/n5_q3_complex.mtx was created -# doc/_Chapter_Examples.xml:80-91 -gap> lis:=ReadMTXE("tmp/n5_q3_complex.mtx");; +# doc/_Chapter_Examples.xml:79-90 +gap> lis:=ReadMTXE("matrices/n5_q3_complex.mtx");; gap> lis[1]; # the field GF(3) gap> lis[2]; # converted to `pair=1` @@ -41,7 +40,7 @@ gap> Display(lis[3]); 2 . . . 1 . . 1 . 2 . 2 2 . . . 1 . . 1 -# doc/_Chapter_Examples.xml:114-122 +# doc/_Chapter_Examples.xml:113-121 gap> filedir:=DirectoriesPackageLibrary("QDistRnd","matrices");; gap> lisX:=ReadMTXE(Filename(filedir,"QX80.mtx"),0);; gap> GX:=lisX[3];;