documentation update

QEC-pages · Oct 16, 2024 · 2723a1e · 2723a1e
1 parent 7f28278
commit 2723a1e
Show file tree

Hide file tree

Showing 4 changed files with 89 additions and 157 deletions.
diff --git a/Doxyfile b/Doxyfile
@@ -93,14 +93,6 @@ ALLOW_UNICODE_NAMES    = NO
 
 OUTPUT_LANGUAGE        = English
 
-# The OUTPUT_TEXT_DIRECTION tag is used to specify the direction in which all
-# documentation generated by doxygen is written. Doxygen will use this
-# information to generate all generated output in the proper direction.
-# Possible values are: None, LTR, RTL and Context.
-# The default value is: None.
-
-OUTPUT_TEXT_DIRECTION  = None
-
 # If the BRIEF_MEMBER_DESC tag is set to YES, doxygen will include brief member
 # descriptions after the members that are listed in the file and class
 # documentation (similar to Javadoc). Set to NO to disable this.
@@ -1325,15 +1317,6 @@ HTML_COLORSTYLE_SAT    = 100
 
 HTML_COLORSTYLE_GAMMA  = 80
 
-# If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML
-# page will contain the date and time when the page was generated. Setting this
-# to YES can help to show when doxygen was last run and thus if the
-# documentation is up to date.
-# The default value is: NO.
-# This tag requires that the tag GENERATE_HTML is set to YES.
-
-HTML_TIMESTAMP         = NO
-
 # If the HTML_DYNAMIC_MENUS tag is set to YES then the generated HTML
 # documentation will contain a main index with vertical navigation menus that
 # are dynamically created via JavaScript. If disabled, the navigation index will
@@ -1628,17 +1611,6 @@ HTML_FORMULA_FORMAT    = png
 
 FORMULA_FONTSIZE       = 10
 
-# Use the FORMULA_TRANSPARENT tag to determine whether or not the images
-# generated for formulas are transparent PNGs. Transparent PNGs are not
-# supported properly for IE 6.0, but are supported on all modern browsers.
-#
-# Note that when changing this option you need to delete any form_*.png files in
-# the HTML output directory before the changes have effect.
-# The default value is: YES.
-# This tag requires that the tag GENERATE_HTML is set to YES.
-
-FORMULA_TRANSPARENT    = YES
-
 # The FORMULA_MACROFILE can contain LaTeX \newcommand and \renewcommand commands
 # to create new LaTeX commands to be used in formulas as building blocks. See
 # the section "Including formulas" for details.
@@ -1942,16 +1914,6 @@ LATEX_BATCHMODE        = NO
 
 LATEX_HIDE_INDICES     = NO
 
-# If the LATEX_SOURCE_CODE tag is set to YES then doxygen will include source
-# code with syntax highlighting in the LaTeX output.
-#
-# Note that which sources are shown also depends on other settings such as
-# SOURCE_BROWSER.
-# The default value is: NO.
-# This tag requires that the tag GENERATE_LATEX is set to YES.
-
-LATEX_SOURCE_CODE      = NO
-
 # The LATEX_BIB_STYLE tag can be used to specify the style to use for the
 # bibliography, e.g. plainnat, or ieeetr. See
 # https://en.wikipedia.org/wiki/BibTeX and \cite for more info.
@@ -1960,14 +1922,6 @@ LATEX_SOURCE_CODE      = NO
 
 LATEX_BIB_STYLE        = plain
 
-# If the LATEX_TIMESTAMP tag is set to YES then the footer of each generated
-# page will contain the date and time when the page was generated. Setting this
-# to NO can help when comparing the output of multiple runs.
-# The default value is: NO.
-# This tag requires that the tag GENERATE_LATEX is set to YES.
-
-LATEX_TIMESTAMP        = NO
-
 # The LATEX_EMOJI_DIRECTORY tag is used to specify the (relative or absolute)
 # path from which the emoji images will be read. If a relative path is entered,
 # it will be relative to the LATEX_OUTPUT directory. If left blank the
@@ -2032,16 +1986,6 @@ RTF_STYLESHEET_FILE    =
 
 RTF_EXTENSIONS_FILE    =
 
-# If the RTF_SOURCE_CODE tag is set to YES then doxygen will include source code
-# with syntax highlighting in the RTF output.
-#
-# Note that which sources are shown also depends on other settings such as
-# SOURCE_BROWSER.
-# The default value is: NO.
-# This tag requires that the tag GENERATE_RTF is set to YES.
-
-RTF_SOURCE_CODE        = NO
-
 #---------------------------------------------------------------------------
 # Configuration options related to the man page output
 #---------------------------------------------------------------------------
@@ -2138,15 +2082,6 @@ GENERATE_DOCBOOK       = NO
 
 DOCBOOK_OUTPUT         = docbook
 
-# If the DOCBOOK_PROGRAMLISTING tag is set to YES, doxygen will include the
-# program listings (including syntax highlighting and cross-referencing
-# information) to the DOCBOOK output. Note that enabling this will significantly
-# increase the size of the DOCBOOK output.
-# The default value is: NO.
-# This tag requires that the tag GENERATE_DOCBOOK is set to YES.
-
-DOCBOOK_PROGRAMLISTING = NO
-
 #---------------------------------------------------------------------------
 # Configuration options for the AutoGen Definitions output
 #---------------------------------------------------------------------------
@@ -2325,15 +2260,6 @@ EXTERNAL_PAGES         = YES
 # Configuration options related to the dot tool
 #---------------------------------------------------------------------------
 
-# If the CLASS_DIAGRAMS tag is set to YES, doxygen will generate a class diagram
-# (in HTML and LaTeX) for classes with base or super classes. Setting the tag to
-# NO turns the diagrams off. Note that this option also works with HAVE_DOT
-# disabled, but it is recommended to install and use dot, since it yields more
-# powerful graphs.
-# The default value is: YES.
-
-CLASS_DIAGRAMS         = YES
-
 # You can include diagrams made with dia in doxygen documentation. Doxygen will
 # then run dia to produce the diagram and insert it in the documentation. The
 # DIA_PATH tag allows you to specify the directory where the dia binary resides.
@@ -2366,23 +2292,6 @@ HAVE_DOT               = YES
 
 DOT_NUM_THREADS        = 0
 
-# When you want a differently looking font in the dot files that doxygen
-# generates you can specify the font name using DOT_FONTNAME. You need to make
-# sure dot is able to find the font, which can be done by putting it in a
-# standard location or by setting the DOTFONTPATH environment variable or by
-# setting DOT_FONTPATH to the directory containing the font.
-# The default value is: Helvetica.
-# This tag requires that the tag HAVE_DOT is set to YES.
-
-DOT_FONTNAME           = Helvetica
-
-# The DOT_FONTSIZE tag can be used to set the size (in points) of the font of
-# dot graphs.
-# Minimum value: 4, maximum value: 24, default value: 10.
-# This tag requires that the tag HAVE_DOT is set to YES.
-
-DOT_FONTSIZE           = 10
-
 # By default doxygen will tell dot to use the default font as specified with
 # DOT_FONTNAME. If you specify a different font using DOT_FONTNAME you can set
 # the path where dot can find it using this tag.
@@ -2619,18 +2528,6 @@ DOT_GRAPH_MAX_NODES    = 50
 
 MAX_DOT_GRAPH_DEPTH    = 0
 
-# Set the DOT_TRANSPARENT tag to YES to generate images with a transparent
-# background. This is disabled by default, because dot on Windows does not seem
-# to support this out of the box.
-#
-# Warning: Depending on the platform used, enabling this option may lead to
-# badly anti-aliased labels on the edges of a graph (i.e. they become hard to
-# read).
-# The default value is: NO.
-# This tag requires that the tag HAVE_DOT is set to YES.
-
-DOT_TRANSPARENT        = NO
-
 # Set the DOT_MULTI_TARGETS tag to YES to allow dot to generate multiple output
 # files in one run (i.e. multiple -o and -T options on the command line). This
 # makes dot run faster, but since only newer versions of dot (>1.8.10) support

diff --git a/introduction.md b/introduction.md
@@ -5,7 +5,7 @@ Date: 2024-08-01
 ## Overview
 
 The program implements two algorithms for calculating the distance of
-a classical or quantum CSS binary code:
+a classical linear binary code or a quantum CSS qubit code:
 
 - Random information set (also, random window, or `RW`), to calculate
   the upper distance bound, and
@@ -18,14 +18,12 @@ parity-check matrix, should be specified.
 For a quantum CSS code, matrix `H=Hx` and either `G=Hz` or `L=Lx`
 matrices are needed.
 
-All matrices with entries in `GF(2)` should have the same number of
-columns, `n`, and obey the following orthogonality conditions:
-$$H_XH_Z^T=0,\quad H_XL_Z^T=0,\quad L_XH_Z^T=0,\quad L_XL_Z^T=I,$$
-where \f$I\f$ is an identity matrix.  Notice that the latter identity is
-not required; it is sufficient that `Lx` and `Lz` matrices have the
-same full row rank `=k`, the dimension of the code, each row of `Lx`
-has a non-zero scalar product with a row of `Lz`, and vice versa.
-
+All matrices with entries in `GF(2)` should have the same number of columns,
+`n`, and obey the following orthogonality conditions: $$H_XH_Z^T=0,\ \ \ \
+H_XL_Z^T=0,\ \ \ \ L_XH_Z^T=0,\ \ \ \ L_XL_Z^T=I,$$ where \f$I\f$ is an identity
+matrix.  Notice that the latter identity is not required; it is sufficient that
+matrices `Lx`, `Lz`, and the product \f$L_XL_Z^T\f$ have the same full row rank
+\f$k\f$, which is also the dimension of the code (number of encoded qubits).
 
 
 ## How it works: RW algorithm (method=1)
@@ -75,40 +73,87 @@ Additional command-line parameters relevant for this method:
 - `start` the position to start the cluster.  In this case only one
   starting position `i=start` will be used.  This is useful, e.g., if
   the code is symmetric (as, e.g., for cyclic codes).
+
+With `debug&2` non-zero, the program in this mode also displays the minimum
+weight of the syndrome found for each error weight `w`.  Example (run from
+`dist-m4ri/src/`)
+
+```sh
+./dist_m4ri debug=3 finH= ../examples/c204H.mmx method=2 wmax=10
+# read H <- file '../examples/c204H.mmx'
+# recursively searching for w=1 codewords wmax=10 beg=0 end=194
+# recursively searching for w=2 codewords wmax=10 beg=0 end=194
+# recursively searching for w=3 codewords wmax=10 beg=0 end=194
+# recursively searching for w=4 codewords wmax=10 beg=0 end=194
+# recursively searching for w=5 codewords wmax=10 beg=0 end=194
+# recursively searching for w=6 codewords wmax=10 beg=0 end=194
+# recursively searching for w=7 codewords wmax=10 beg=0 end=194
+# recursively searching for w=8 codewords wmax=10 beg=0 end=194
+# w=1 min syndrome weight 2
+# w=2 min syndrome weight 3
+# w=3 min syndrome weight 3
+# w=4 min syndrome weight 2
+# w=5 min syndrome weight 1
+# w=6 min syndrome weight 1
+# w=7 min syndrome weight 1
+# w=8 min syndrome weight 0
+### Cluster (actual min-weight codeword found): dmin=8
+success  (found min-weight codeword) d=8
+
+```
 
 ## How to run it
 
 For help, just run `./dist_m4ri -h` or `./dist_m4ri --help`.  This
 shows the following 
 ```sh
 $ ./dist_m4ri --help 
-./dist_m4ri: calculate the minumum distance of a q-LDPC code
-        usage: ./dist_m4ri [arguments [...]]
-Supported parameters:
-        debug=[int]:     bitmap for aux information (3)
-        fin=[string]: base name for input files ("try")
-                 finH->"${try}X.mtx"  finG->"${try}X.mtx"
-        finH=[str]: parity check matrix Hx (NULL)
-        finG=[str]: matrix Hz or NULL for classical code (NULL)
-        finL=[str]: matrix Lx or NULL for classical code (NULL)
-                 Either L=Lx or G=Hz matrix is required for a quantum CSS code
-        css=1: this is a CSS code (the only supported one) (1)
-        seed=[int]: rng seed  [0 for time(NULL)]
-        method=[int]: bitmap for method used:
-                1: random window (RW) algorithm
-                2: connected cluster (CC) algorithm
-        steps=[int]: how many RW decoding cycles to use (1)
-        wmax=[int]: max cluster weight in CC (5)
-        wmin=[int]: min distance of interest in RW (1)
-        -h or --help gives this help
+./dist_m4ri: distance of a classical or quantum CSS code
+	usage: ./dist_m4ri parameter=value [...]
+
+   Required parameter:
+	method=[int]: bitmap for method used (required, default 0: none): 
+		1: random window (RW) algorithm. Options:
+		   steps=[int]: how many information sets to use (1)
+		   wmin=[int]:  minimum distance of interest (1)
+		2: connected cluster (CC) algorithm.  Options:
+		   wmax=[int]:  maximum cluster weight (5) 
+		   start=[int]: use only this position to start (-1)
+
+   General parameters:
+	finH=[str]: parity check matrix Hx (NULL)
+	finG=[str]: matrix Hz (quantum CSS code only) (NULL)
+	finL=[str]: matrix Lx (quantum CSS code only) (NULL)
+		 Either L=Lx or G=Hz matrix is required for a quantum CSS code
+	fin=[str]:  base name for input files ("try")
+		 set finH->"${fin}X.mtx"  finG->"${fin}Z.mtx"
+	css=[int]:  reserved for future use (1)
+	seed=[int]: rng seed [use 0 for time(NULL)] (0)
+	debug=[int]:	 bitmap for aux information to output (3)
+		0: clear the entire debug bitmap to 0.
+		1: output misc general info (on by default)
+		2: output more general info (on by default)
+		4: debug command line arguments parsing
+		8: output progress reports every 1000 steps
+		16: output new min-weight codewords found (cut large vectors)
+		32: output matrices (unless n is large)
+		64: reserved
+		128: reserved
+		256: print out neighbor lists
+		512: print out vectors/syndrome weights during recursion
+		1024: print piv/skip_pivs/reserved
+		2048: allow big matrix / large vector output
+		   see the source code for more options
+	  Multiple 'debug' parameters are XOR combined except for 0.
+	  Use debug=0 as the 1st argument to suppress all debug messages.
+   -h gives this help (also '--help')
 ```
 
 ## Compilation
 
-The program is intended for use with recent `gcc` compilers under
-linux.  Download the distribution from `github` then run from the
-`dist-m4ri/src` directory ```sh make -j all ``` This should compile
-the executable `dist_m4ri`.
+The program is intended for use with recent `gcc` compilers under linux.
+Download the distribution from `github` then run from the `dist-m4ri/src`
+directory ```sh make -j all ``` This should compile the executable `dist_m4ri`.
 
 The program uses `m4ri` library for binary linear algebra.  To install
 under Ubuntu, run
@@ -119,26 +164,9 @@ sudo apt-get install -y libm4ri-dev
 
 
 ## Documentation 
-The document for this package is available at [https://qec-pages.github.io/dist-m4ri/](https://qec-pages.github.io/dist-m4ri/). The package is hosted on [github](https://github.com/QEC-pages/dist-m4ri)
+The document for this package is available at
+[https://qec-pages.github.io/dist-m4ri/](https://qec-pages.github.io/dist-m4ri/). The
+package is hosted on [github](https://github.com/QEC-pages/dist-m4ri)
 
 This file (`introduction.md`) is used as the main page for the doxygen documentation.
 
-### Formula syntax
-
-Inline formula: here \f$ a \f$ is random variable. \f$J \in {-1,1} \f$, 
-and (display mode) \f[ x \in (0,\infty) \f]
-
-Then one can compute \f$y\f$ as (display mode)
-$$ y=a \exp(-Jx) $$
-
-$single dollar sign$ is not supported for inline formulas
-
-### Code blocks
-
-A `Python` function can be defined as
-```
-def add(a,b):
-    return a+b
-```
-
-### Inline code block `y=\exp(Jx)` is not supported in section titles, how about just use (method = 1)
diff --git a/src/dist_cc.c b/src/dist_cc.c
@@ -179,6 +179,13 @@ static inline void one_ordered_pos_del(one_vec_t * const err, _maybe_unused cons
  * @param err error vector with sorted components 
  * @param urr unsorted vector so far 
  * @param syn array of syndrome vectors with sorted components (indexed by weight of error)
+ * @param wmax max recursion level (max weight of an error to process)
+ * @param max_col_wt maximum column weight (used to predict early termination)
+ * @param mH matrix `H` (check matrix of the code or `Hx` for a CSS code)
+ * @param mHT matrix `H` transposed
+ * @param mL matrix `L=Lx` for a CSS code, or `NULL` for a classical binary code, used to check whether zero-syndrome error is trivial or not
+ * @param p_swei minimum syndrome weight array
+ * @param debug bitmap 
  */
 int start_CC_recurs(one_vec_t *err, one_vec_t *urr, one_vec_t * const syn[],
 		    const int wmax, const int max_col_wt, 

diff --git a/src/makefile b/src/makefile
@@ -36,8 +36,8 @@ mmio.o: mmio.c mmio.h makefile
 clean:
 	rm -f *~ *.tmp *.out *.o ../input/*~ ../examples/*~ TAGS 
 
-#dox: 
-#	doxygen ../Doxyfile mainpage.h
+dox: 
+	cd .. && doxygen Doxyfile 
 
 tags:
 	etags *.c *.h