Documentation update and misc minor changes (#33)

* Ensure all functions are documented properly

* moved example programs to examples/ directory

* documentation update

* bibliography renamed

* tmp directory is no longer needed

.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
+/doc/manual.six
+/matrices/n5_q3_complex.mtx

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 :=

doc/body.autodoc

@@ -131,10 +131,10 @@ obtained as the first row of $G_S$.
 <Cite Key="Cuellar-etal-2020"/>).
 
 @Subsection CSS version of the algorithm
-@SubsectionLabel DistRandCSS
+@SubsectionLabel AlgorithmCSS
 
-The described version of the algorithm is implemented in the function
-<Ref Func="DistRandCSS"/>.  It applies to the case of
+The described version of the algorithm is implemented in the function `DistRandCSS`
+(<Ref Sect="Section_DistanceFunctions"/>).  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 <Ref Func="DistRandStab"/>.
+implemented in the function `DistRandStab` (<Ref Sect="Section_DistanceFunctions"/>).
 
 **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` <Ref Sect="Section_DistanceFunctions"/>, whenever more
+`DistRandStab` (<Ref Sect="Section_DistanceFunctions"/>), 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 <Ref
+  accepted by the function `DistRandCSS`, see Section <Ref
   Sect="Section_DistanceFunctions"/>.
 
 * 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` <Ref
-Sect="Section_DistanceFunctions"/> assumes the generator matrix with
+For efficiency reasons, the function `DistRandStab` (<Ref
+Sect="Section_DistanceFunctions"/>) 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

lib/cyclic.g → 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

lib/examples.g → 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`
@@ -119,7 +118,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 +131,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

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 <Ref Sect="Section_Empirical"/> 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("<n>=", 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 <Ref Chap="Chapter_FileFormat"/> 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;
@@ -885,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 <Ref
-#!  Subsect="Subsection_DistRandStab"/> (**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` <Ref Func="DistRandCSS"/>.
+#!  `DistRandCSS` <Ref Sect="Section_DistanceFunctions"/>.
 #!  * `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
@@ -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);

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(

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];;