diff --git a/Doxyfile b/Doxyfile index 1c2a6b0..b8df8df 100644 --- 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 index 5ff43fd..b15e4ef 100644 --- 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,6 +73,34 @@ 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 @@ -82,33 +108,52 @@ 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 index 3c8a0ac..bfb9e4f 100644 --- 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 index ab9be10..f6ebe40 100644 --- 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