### Install m4ri Library on Ubuntu

Source: https://github.com/qec-pages/vecdec/blob/main/README.md

Use these commands to install the m4ri library on an Ubuntu system.

```bash
sudo apt-get update -y
sudo apt-get install -y libm4ri-dev
```

--------------------------------

### Example DEM File Structure

Source: https://context7.com/qec-pages/vecdec/llms.txt

This example shows the structure of a Stim-compatible Detector Error Model (DEM) file, defining error events with probabilities and affected detectors, as well as detector definitions.

```plaintext
# Example DEM file structure (rep_code3.dem)
error(0.125) D0
error(0.125) D0 D1
error(0.125) D0 D2
error(0.125) D1 D3
error(0.125) D1 L0
error(0.125) D2 D4
error(0.125) D3 D5
error(0.125) D4 D6
error(0.125) D5 D7
detector(1, 0) D0
detector(3, 0) D1
shift_detectors(0, 1) 0
detector(1, 0) D2
detector(3, 0) D3
```

--------------------------------

### DEM File Example

Source: https://github.com/qec-pages/vecdec/blob/main/README.md

This is an example of a Detector Error Model (DEM) file generated by the 'stim' library. It defines errors and detector positions.

```stim
error(0.125) D0
error(0.125) D0 D1
error(0.125) D0 D2
error(0.125) D1 D3
error(0.125) D1 L0
error(0.125) D2 D4
error(0.125) D3 D5
error(0.125) D4 D6
error(0.125) D5 D7
detector(1, 0) D0
detector(3, 0) D1
shift_detectors(0, 1) 0
detector(1, 0) D2
detector(3, 0) D3
shift_detectors(0, 1) 0
detector(1, 0) D4
detector(3, 0) D5
detector(1, 1) D6
detector(3, 1) D7
```

--------------------------------

### Piecewise Decoding with BP

Source: https://github.com/qec-pages/vecdec/blob/main/USAGE.adoc

Example of piecewise decoding using BP.

```sh
include::examples/ex_YBP.sh[]
```

```sh
include::examples/ex_YBP_sh.out[lines="6..-1"]
```

--------------------------------

### Clone m4ri library

Source: https://github.com/qec-pages/vecdec/blob/main/README.md

Clone the m4ri library from GitHub to compile and install it.

```bash
git clone https://github.com/malb/m4ri/
```

--------------------------------

### Run basic vectorized decoder help

Source: https://github.com/qec-pages/vecdec/blob/main/README.md

Displays help information for the basic vectorized (random information set) decoder mode.

```sh
./vecdec mode=0 --help
```

--------------------------------

### Run iterative decoder help

Source: https://github.com/qec-pages/vecdec/blob/main/README.md

Displays help information for the iterative decoder mode, including submode configurations.

```sh
./vecdec mode=1 --help
```

--------------------------------

### Configure Quantized LLR

Source: https://context7.com/qec-pages/vecdec/llms.txt

Sets parameters for LLR quantization, including switching between Sum-Product and Min-Sum algorithms.

```bash
# Sum-Product algorithm (default)
./src/vecdec mode=1 qllr1=12 qllr2=300 qllr3=7 ...

# Min-Sum algorithm (qllr2=0)
./src/vecdec mode=1 qllr2=0 finH=$code ntot=1000000 nvec=100000 useP=0.03

# qllr1=12  : power for LLR quantization (1<<qllr1)
# qllr2=300 : number of table entries for LLR operations
# qllr3=7   : table resolution is 2^(-(qllr1-qllr3))
```

--------------------------------

### Configure Pre-Decoder

Source: https://context7.com/qec-pages/vecdec/llms.txt

Sets up the cluster-based pre-decoder to accelerate processing, with options to disable or limit its scope.

```bash
# Configure pre-decoder with custom parameters
./src/vecdec mode=0 steps=1000 seed=7 \
    finH=./examples/96.3.963.alist useP=0.05 \
    ntot=1000 nvec=1000 \
    uW=2 uR=1 maxU=10000

# uW=2   : store error clusters up to weight 2 in hash
# uR=1   : max graph distance between set bits in stored errors
# maxU=0 : no limit on hash size (default)

# Disable pre-decoder entirely:
./src/vecdec mode=0 uW=-1 ...

# Skip only zero-syndrome vectors (minimal pre-decoding):
./src/vecdec mode=0 uW=0 ...
```

--------------------------------

### List Command-Line Parameters

Source: https://github.com/qec-pages/vecdec/blob/main/todo.md

A list of available command-line parameters and their associated modes for the vecdec tool.

```text
debug
mode
seed
qllr1
qllr2
qllr3

ntot // mode 0,1
nvec // mode 0.1
pads // mode 0,1 reading syndrome vectors only (fdet)
nfail // mode 0,1 early termination condition 
steps // mode 0,1,2 
swait // mode 0 and mode 2   early termination condition 
lerr  // mode 1 max OSD level (-1 for no OSD)
// mode 0 (-1 is same as 0)

useP DEM parameter

dmin // early termination with mode=2

maxosd // only for BP
maxC // error if too long nz file, limit the number of CWs in do_LLR_dist (RIS)
bpalpha
bpretry
epsilon // not used 
dE  // only mode=2 
dW  // mode=2 and mode=3 when constructing G and L matrix
maxW // upper bound for creating / reading CWs / mode=2 and mode=3

debug 1 possibly relevant information
debug 2 output matrix ranks
debug 4 parsing input variables 
debug 8 file i/o messages
```

--------------------------------

### Use Externally Generated Error Vectors with Stim

Source: https://github.com/qec-pages/vecdec/blob/main/USAGE.adoc

Integrate externally generated error vectors, detector events, or observables, for example, those created by Stim. This allows for using pre-computed or simulated data.

```sh
vecdec --mode 0 --in ./examples/surf_d3.dem --ferr ./examples/err.vec --gdet tmpA.01 --gobs tmpB.01
```

```sh
tmpA.01
tmpB.01
```

--------------------------------

### Sample Stim command-line for binary vector generation

Source: https://github.com/qec-pages/vecdec/blob/main/todo.md

Use this command to generate binary vectors in 01 format from a Stim detector error model file.

```bash
stim sample_dem \
  --shots 5 \
  --in example.dem \
  --out dets.01 \
  --out_format 01 \
  --obs_out obs_flips.01 \
  --obs_out_format 01
```

--------------------------------

### Write Detector Events and Observables to Files

Source: https://github.com/qec-pages/vecdec/blob/main/USAGE.adoc

In mode=0 and mode=1, detector events and observables can be written to files using gdet and gobs arguments. Use steps=0 and uW=-1 to prevent decoding and ensure all generated data is written.

```sh
vecdec --mode 0 --steps 0 --uW -1 --in ./examples/surf_d3.dem --gdet tmpA.01 --gobs tmpB.01
```

```sh
2000 lines to each of the output files tmpA.01 and tmpB.01
```

--------------------------------

### Simulate classical code performance with Belief Propagation (BP) decoder and OSD

Source: https://github.com/qec-pages/vecdec/blob/main/USAGE.adoc

Uses the Belief Propagation (BP) decoder with a specified number of steps and update schedule, followed by OSD1 post-decoder. The output statistics include counts for BP convergence and OSD success.

```sh
vecdec --code ./examples/96.3.963.alist --steps 10 --mode 1.6 --lerr 1 --maxosd 50 --seed 123
```

--------------------------------

### Vecdec General Help: Code Matrices and Parameters

Source: https://github.com/qec-pages/vecdec/blob/main/README.md

Provides an overview of matrices used by vecdec, including CSS codes, generator matrices (Hx, Hz, Lx, Lz), and error probability vectors (P). It explains how DEM files are used and how matrices can be specified independently. It also details general parameters like 'seed' for randomness.

```sh
   Matrices used by ./src/vecdec:
	 We have a CSS code with binary generator matrices Hx=H, Hz=G, 
	 and logical-operator generating matrices Lx=L and Lz=K.  These
	 matrices have 'n' columns each and satisfy orthogonality properties
		 Hx*Hz^T=0, Lx*Hz^T=0, Lx*Lz^T=0, and Lx*Lz^T=I (identity matrix).
	 We are trying to correct binary Z errors, whose probabilities
	 are given by the n-component double vector P
	  (or can be overridden with the command-line parameter 'useP').
		   A detector error model (DEM) file, in the format produced by Stim, 
	 contains matrices Hx and Lx, and the error probability vector P.
	 The same code can be obtained by specifying the matrices 
	 independently, via separate files.

   The dual CSS matrix Hz can be specified instead of Lx.
	 In such a case, the internal error generator must be used
	 (an attempt to specify 'fdet' and 'fobs' files will result in an error).

   For a classical code, just give the parity check matrix Hx=H.
	 In this case G matrix is trivial (has zero rank), and
	 Lx has all rows of weight '1'.  
	 Only the internal error generator can be used for classical codes
	                                                       
   Note: detection events (syndrome bits) are given by the product 'H*e'
		       observables are given by 'L*e'
		                                                          
	 Parameter(s) used by all modes:                         
	 seed=[integer] : when negative or zero, combine provided value
		 with 'time(null)' and 'pid()' for more randomness.
	                                                       
```

--------------------------------

### Compile m4ri with custom paths

Source: https://github.com/qec-pages/vecdec/blob/main/README.md

Compile the m4ri library specifying include and library paths in the Makefile or during make.

```bash
make -j all DINC="-I../../m4ri -L../../m4ri/.libs"
```

--------------------------------

### Perform Incremental Codeword Search

Source: https://context7.com/qec-pages/vecdec/llms.txt

Demonstrates an initial search followed by a continuation search that resumes from previously saved codewords.

```bash
# Initial search
./src/vecdec mode=2.1 steps=100000 seed=7 \
    finH=./examples/96.3.963.alist useP=0.05 outC=tmp.nz dW=10

# Continue search from saved codewords
./src/vecdec mode=2.1 steps=100000 seed=0 \
    finH=./examples/96.3.963.alist useP=0.05 outC=tmp.nz finC=tmp.nz dW=10
```

--------------------------------

### Simulate Quantum Clifford Circuit

Source: https://github.com/qec-pages/vecdec/blob/main/USAGE.adoc

Sets up variables for simulating a quantum Clifford circuit with a detector error model.

```sh
vecdec=./src/vecdec
stim=../Stim/out/stim # location of `stim` command-line binary
d=5                      # code distance (and number of rounds)
p=0.005                  # error probability to use
fnam=sd5                 # base file name to use for `stim` files
```

--------------------------------

### Compile vecdec program

Source: https://github.com/qec-pages/vecdec/blob/main/README.md

Compile the vecdec program using make. Navigate to the src directory first.

```bash
cd vecdec/src
make -j all
```

--------------------------------

### Workflow Script Logic

Source: https://github.com/qec-pages/vecdec/blob/main/todo.md

A conceptual workflow for processing intervals and decoding using vecdec.

```text
input: intervals [(0 r1), (q2 r2), (q3 r3) ...] and [(0,c1), (b2,c2),,, ]; DEM
1. generate initial DET and OBS files
2. write H, L, P from DEM (vecdec mode=3)
3. for each interval
  - cut the DET rows (cut)
  - cut the matrix: rowblock [A B 0] into A and B
  - use A and existing errors `e` to construct modified DET (A e+s)
  - use B to decode (vecdec); output error vector using `perr`
  - use (cut) and (paste) to update errors `e`
4. At the end use `e` as the predicted error to verify the observables
```

--------------------------------

### Run bs.sh Script

Source: https://github.com/qec-pages/vecdec/blob/main/examples/README.md

Execute the bs.sh script to automatically create a Bacon-Shor circuit, generate error models for each p1 value, and run vecdec for decoding data. Ensure 'stim', 'python', and 'gnuplot' variables are correctly set in surf12.sh and/or bs.sh.

```sh
sh bs.sh
```

--------------------------------

### Basic RIS Decoding on Classical LDPC Code

Source: https://context7.com/qec-pages/vecdec/llms.txt

Use this for basic Random Information Set (RIS) decoding on classical LDPC codes. Ensure the `.alist` file is correctly specified.

```bash
./src/vecdec mode=0 seed=7 steps=5000 \
    finH=./examples/96.3.963.alist useP=0.05 \
    ntot=1000 nvec=1000
```

--------------------------------

### Generate Stim Circuit and Run RIS Decoding

Source: https://github.com/qec-pages/vecdec/blob/main/USAGE.adoc

Creates a surface code circuit using Stim and performs RIS decoding with vecdec.

```sh
$stim gen --code surface_code --task rotated_memory_x \
          --distance $d --rounds $d \
          --after_clifford_depolarization $p \
          --after_reset_flip_probability $p \
          --before_round_data_depolarization $p \
          --before_measure_flip_probability $p \
          > $fnam.stim
# use `Stim` to create the DEM file
$stim analyze_errors --in $fnam.stim > $fnam.dem
# use `vecdec` to generate errors internally and do the actual decoding
$vecdec debug=1 mode=0 fdem=$fnam.dem steps=500 lerr=1 \
          ntot=10240 nvec=1024 nfail=100
```

--------------------------------

### Vary decoder parameters `steps` and `lerr`

Source: https://github.com/qec-pages/vecdec/blob/main/USAGE.adoc

Demonstrates the effect of varying the decoder parameters `steps` and `lerr` on the performance of a classical code.

```sh
vecdec --code ./examples/96.3.963.alist --steps 1000 --lerr 1 --seed 123
```

--------------------------------

### Simulate classical code performance with default RIS decoder

Source: https://github.com/qec-pages/vecdec/blob/main/USAGE.adoc

Use the default RIS decoder (`mode=0 lerr=1`) with specified steps and error levels. The pre-decoder parameter `uW` controls the weight of errors added to the syndrome hash for matching.

```sh
vecdec --code ./examples/96.3.963.alist --steps 5000 --mode 0 --lerr 1 --uW 1 --seed 123
```

--------------------------------

### Split 01 Files

Source: https://github.com/qec-pages/vecdec/blob/main/USAGE.adoc

Uses the cut command to select specific columns from a 01 file.

```sh
cut -c 3-5 dets.01
```

--------------------------------

### Simulate Quantum Circuit Performance

Source: https://github.com/qec-pages/vecdec/blob/main/USAGE.adoc

Simulate a rotated surface code using a detector error model (DEM) file generated by stim.

```sh
include::examples/ex_C3.sh[]
```

```sh
include::examples/ex_C3_sh.out[]
```

--------------------------------

### Create K=Lz Matrix with Minimum Weight Rows

Source: https://github.com/qec-pages/vecdec/blob/main/USAGE.adoc

Generate the K=Lz matrix with guaranteed minimum weight rows from the same set of codewords used for G. This can be done using the same input DEM file.

```sh
vecdec --mode 3 --dW 0 --maxW 3 --in ./examples/surf_d3.dem --out tmpG --outK tmpK
```

```sh
tmpG.mmx
tmpK.mmx
```

--------------------------------

### Vecdec Mode 0: Basic Vectorized Decoder

Source: https://github.com/qec-pages/vecdec/blob/main/README.md

Details on using the basic vectorized decoder (mode 0), its parameters, and input/output file handling.

```APIDOC
## POST /vecdec mode=0

### Description
Uses a basic vectorized decoder. This mode is exponentially slow but not specific to quantum LDPC codes. Accuracy and performance are determined by 'steps' and 'lerr'. Long codes may require exponentially large 'steps'.

### Method
POST

### Endpoint
`/vecdec`

### Parameters
#### Query Parameters
- **mode** (integer) - Required - Set to 0 for the basic vectorized decoder.
- **steps** (integer) - Optional - Number of RIS rounds. Determines accuracy and performance.
- **lerr** (integer) - Optional - Determines accuracy and performance. Values > 1 can be slow for long codes.
- **fdem** (string) - Optional - Path to a single DEM file.
- **finH** (string) - Optional - Path to input file for H matrix.
- **finL** (string) - Optional - Path to input file for L matrix (required for quantum codes if finG is not used).
- **finP** (string) - Optional - Path to input file for P matrix.
- **finG** (string) - Optional - Path to input file for G matrix (needed for quantum codes if finL is not used).
- **useP** (boolean) - Optional - Overrides error probability values in DEM file.
- **mulP** (float) - Optional - Scales error probability values from DEM file.
- **ferr** (string) - Optional - Path to a file containing errors (01 format).
- **fdet** (string) - Optional - Path to a file with detector events.
- **fobs** (string) - Optional - Path to a file with observables.
- **nfail** (integer) - Optional - For early termination.
- **swait** (integer) - Optional - For early termination.
- **ntot** (integer) - Optional - Total number of errors to read or generate.
- **nvec** (integer) - Optional - Number of errors to read or generate in chunks.
- **uW** (integer) - Optional - Use hash storage to speed up decoding (non-negative).
- **maxU** (integer) - Optional - Limit on the number of syndrome vectors in the hash (0 for no limit).
- **uR** (integer) - Optional - Limit on the v-v graph distance between non-zero positions in stored error vectors (0 for no limit).
- **uX** (integer) - Optional - Bitmap for experimental cluster-based predecoder options (default: 0). Use with caution.

### Request Example
```json
{
  "mode": 0,
  "steps": 100,
  "lerr": 1,
  "fdem": "path/to/code.dem"
}
```

### Response
#### Success Response (200)
- **status** (string) - Decoding status message.
- **decoded_errors** (integer) - Number of errors decoded.

#### Response Example
```json
{
  "status": "Decoding successful",
  "decoded_errors": 5
}
```
```

--------------------------------

### Basic Parallel BP Decoder with OSD Post-Processing

Source: https://context7.com/qec-pages/vecdec/llms.txt

Perform Belief Propagation (BP) decoding using the parallel update schedule. OSD post-processing (`lerr`) can be enabled for improved accuracy. Adjust `steps` for desired accuracy and performance trade-off.

```bash
./src/vecdec debug=1 mode=1 maxosd=50 steps=10 lerr=1 \
    finH=./examples/96.3.963.alist ntot=1000 nvec=1000 useP=0.05 seed=113
```

--------------------------------

### Reproduce Total Logical Errors by Comparing Det and Obs

Source: https://github.com/qec-pages/vecdec/blob/main/USAGE.adoc

To accurately reproduce the total number of logical errors, compare both detector events and observables simultaneously. This run confirms the FAIL count reported by vecdec.

```sh
vecdec --mode 1.12 --lerr -1 --in ./examples/surf_d3.dem --ferr ./examples/err.vec --gdet tmpA.01 --gobs tmpB.01 --det tmpC.01 --obs tmpD.01 --compare
```

```sh
FAIL: 10
```

--------------------------------

### Create DEM File from Matrices and Probability Vector

Source: https://github.com/qec-pages/vecdec/blob/main/USAGE.adoc

Use mode=3.64 with bit 6 set in submode to create a DEM file from H and L matrices and a P vector. The error probabilities are scaled by mulP.

```sh
vecdec --mode 3.64 --submode 64 --mulP 2 --inH tmpH.mmx --inL tmpL.mmx --inP tmpP.mmx --out tryD.dem
```

```sh
tryD.dem
```

--------------------------------

### Generate H and P matrices from DEM

Source: https://github.com/qec-pages/vecdec/blob/main/USAGE.adoc

Initial step to generate the H matrix and probability vector P from a DEM file.

```sh
$vecdec mode=3.20 fdem= ./examples/surf_d3.dem fout=tmp
```

--------------------------------

### Tune BP Decoder Parameters

Source: https://context7.com/qec-pages/vecdec/llms.txt

Iterates through different OSD levels and iteration counts to optimize BP decoder performance.

```bash
# Compare different OSD levels with BP decoder
for lerr in 0 1 2 3; do
    for steps in 5 10 25 50; do
        ./src/vecdec debug=0 mode=1 maxosd=50 steps=$steps lerr=$lerr \
            finH=./examples/96.3.963.alist ntot=1000 nvec=1000 useP=0.05 seed=113
    done
done
```

--------------------------------

### Implement Piecewise Decoding

Source: https://github.com/qec-pages/vecdec/blob/main/USAGE.adoc

Shell script implementation for piecewise decoding using matrix decomposition.

```sh
include::examples/ex_X9.sh[]
```

```sh
include::examples/ex_X9_sh.out[]
```

--------------------------------

### Run Serial-V BP Decoder

Source: https://context7.com/qec-pages/vecdec/llms.txt

Executes the BP decoder using a serial-V schedule with average LLR, configured via submode 14.

```bash
# Serial-V BP decoder on quantum CSS code
./src/vecdec mode=1.14 steps=10 lerr=2 seed=7 \
    finH=input/QX40.mtx finG=input/QZ40.mtx useP=0.02 \
    nvec=1000 ntot=1000
```

--------------------------------

### Compare Predicted Vectors with Actual Data

Source: https://github.com/qec-pages/vecdec/blob/main/USAGE.adoc

In mode=0 and mode=1, compare predicted error vectors, detector events, and observables with actual data. This run shows correct detector event recovery but some logical errors.

```sh
vecdec --mode 0 --in ./examples/surf_d3.dem --ferr ./examples/err.vec --gdet tmpA.01 --gobs tmpB.01 --det tmpC.01 --obs tmpD.01
```

```sh
all detector events are recovered correctly, but there are some logical errors
```

--------------------------------

### Perform BP Decoding with External Files

Source: https://github.com/qec-pages/vecdec/blob/main/USAGE.adoc

Executes BP decoding using pre-generated H, L, and P matrix files.

```sh
$vecdec mode=1.14 finH=tmpH.mmx finL=tmpL.mmx finP=tmpP.mmx steps=50 lerr=2 \
          ntot=10240 nvec=1024 nfail=100
```

--------------------------------

### Generate Stim and DEM Files

Source: https://github.com/qec-pages/vecdec/blob/main/USAGE.adoc

Constructs a Stim file for a surface code and generates the corresponding detector error model.

```sh
stim=../Stim/out/stim
dist=5
p1=0.003
# construct `stim` file
$stim gen --code surface_code --task rotated_memory_x \
      --distance $dist --rounds $dist \
      --after_clifford_depolarization $p1 \
      --after_reset_flip_probability $p1 \
      --before_round_data_depolarization $p1 \
      --before_measure_flip_probability $p1 \
      > examples/surf_d$dist.stim
# generate the corresponding DEM file
$stim analyze_errors --in examples/surf_d${dist}.stim > examples/surf_d${dist}.dem
```

--------------------------------

### Quantum CSS Code Decoding with Hx and Hz Matrices

Source: https://context7.com/qec-pages/vecdec/llms.txt

Decode quantum CSS codes by providing both the X-check matrix (`finH`) and Z-check matrix (`finG`). This ensures proper logical error detection for quantum codes.

```bash
./src/vecdec mode=0 steps=1000 seed=7 \
    finH=input/QX40.mtx finG=input/QZ40.mtx useP=0.02 \
    nvec=1000 ntot=1000
```

--------------------------------

### Run vecdec error rate comparison

Source: https://github.com/qec-pages/vecdec/blob/main/todo.md

Compares error rates between lerr=0 and lerr=1 configurations using the vecdec tool.

```bash
./src/vecdec  seed=7 steps=5000 lerr=0             finH= ./examples/96.3.963.alist useP=0.05       ntot=10 nvec=10 uW=-1
 ./src/vecdec  seed=7 steps=5000 lerr=1             finH= ./examples/96.3.963.alist useP=0.05       ntot=10 nvec=10 uW=-1
```

--------------------------------

### Simulate CSS Code Performance

Source: https://github.com/qec-pages/vecdec/blob/main/USAGE.adoc

Simulate a hyperbolic CSS code using generator matrices H and G with a specified error probability.

```sh
include::examples/ex_B3.sh[]
```

```sh
include::examples/ex_B3_sh.out[]
```

```sh
include::examples/ex_C1.sh[]
```

```sh
include::examples/ex_C1_sh.out[lines="10..-1"]
```

```sh
include::examples/ex_C2.sh[]
```

```sh
include::examples/ex_C2_sh.out[lines="10..-1"]
```

--------------------------------

### Clone vecdec repository

Source: https://github.com/qec-pages/vecdec/blob/main/README.md

Clone the vecdec source code repository from GitHub.

```bash
git clone https://github.com/QEC-pages/vecdec
```

--------------------------------

### Export Code Matrices to MMX/DEM Files

Source: https://github.com/qec-pages/vecdec/blob/main/USAGE.adoc

Use mode=3 to create code matrices (H, G, L, K) and probability vector (P) from a DEM file. The output files are in Matrix Market format.

```sh
vecdec --mode 3 --in ./examples/surf_d3.dem --out tmp
```

```sh
tmpH.mmx
tmpL.mmx
tmpG.mmx
tmpK.mmax
tmpP.mmx
```

--------------------------------

### Vecdec General Options

Source: https://github.com/qec-pages/vecdec/blob/main/README.md

General options applicable to all vecdec modes, including debug bitmap settings.

```APIDOC
## General Options

### Description
Configures auxiliary information output and general program behavior.

### Parameters
#### Query Parameters
- **debug** (integer) - Optional - Bitmap for auxiliary information output. Defaults to 1.
  - 0: Clears the entire debug bitmap.
  - 1: Outputs miscellaneous general information (on by default).
  - 2: Outputs additional information, including code confinement calculation.
  See source code for more options.
  Multiple 'debug' parameters are XOR combined, except for 0.

### Notes
Refer to program documentation for input file syntax.
```

--------------------------------

### Validate model with Stim

Source: https://github.com/qec-pages/vecdec/blob/main/USAGE.adoc

Compares decoding performance between the original DEM model and the constructed matrices using Stim for event generation.

```sh
stim=../Stim/out/stim
fnam=try
$stim sample_dem --shots 10240 --in ./examples/surf_d3.dem \
        --out $fnam.det --out_format 01 \
        --obs_out $fnam.obs --obs_out_format 01
$vecdec debug=1 mode=1.14 fdem=./examples/surf_d3.dem \
           fdet=$fnam.det fobs=$fnam.obs steps=50 lerr=2 \
           nvec=1024 ntot=10240
$vecdec debug=1 mode=1.14 finH=tmpXH.mmx finL=tmpXL.mmx finP=tmpXP.mmx \
           fdet=$fnam.det fobs=$fnam.obs steps=50 lerr=2 \
           nvec=1024 ntot=10240 pads=1
```

--------------------------------

### Calculate Column Boundaries

Source: https://github.com/qec-pages/vecdec/blob/main/USAGE.adoc

Uses mtx_sub to calculate column boundaries in different row blocks of H.

```sh
include::examples/ex_X8.sh[]
```

```sh
include::examples/ex_X8_sh.out[]
```

--------------------------------

### Create weight-3 codeword list

Source: https://github.com/qec-pages/vecdec/blob/main/USAGE.adoc

Generates a list of classical codewords of weight 3 orthogonal to the rows of H.

```sh
$vecdec mode=2 finH=tmpH.mmx steps=10000 maxW=3 finP= tmpP.mmx outC=tmp.nz
```

--------------------------------

### Estimate Decoding Performance at Small Error Probabilities

Source: https://github.com/qec-pages/vecdec/blob/main/USAGE.adoc

Uses mode 2 to estimate performance by iterating through weight ranges.

```sh
vecdec=./src/vecdec
$vecdec mode=2.0 fdem=sd5.dem steps=100000 dW=7 outC=tmp.nz
for ((w=5; w<=10; w++)) ; do
  echo $w `$vecdec debug=0 mode=2.2 fdem=sd5.dem steps=0 maxW=$w finC=tmp.nz`
done
```

```sh
# min_weight N_min N_use N_tot
5 13800 5471523 5471523
```

--------------------------------

### Verify Syndrome Values

Source: https://github.com/qec-pages/vecdec/blob/main/USAGE.adoc

Executes a shell script to verify syndrome values using BP decoding and saves detector events and predicted errors.

```sh
include::examples/ex_X6.sh[]
```

```sh
include::examples/ex_X6_sh.out[]
```

--------------------------------

### RIS Decoding with OSD Post-Processing

Source: https://context7.com/qec-pages/vecdec/llms.txt

Enhance decoding accuracy for RIS by enabling Ordered Statistics Decoding (OSD) with the `lerr` parameter. Higher `lerr` values increase computation but improve accuracy, especially with fewer steps.

```bash
./src/vecdec debug=0 seed=113 mode=0 \
    finH=./examples/96.3.963.alist 
    ntot=1000 nvec=1000 steps=500 useP=0.05 lerr=1
```

--------------------------------

### Codeword Non-Zero Position Storage Format

Source: https://github.com/qec-pages/vecdec/blob/main/todo.md

Format for storing codeword non-zero positions in a file, where each row represents a column index list for a codeword of weight w.

```text
%% NZLIST
% end-of-line comments followed by rows formed by of column indices (ordered), 
% starting with weight `w`, `1`-based and separated by spaces.
% w  i1 i2 ... iw
4  1 3 7 17
5  2 4 8 23 61
```

--------------------------------

### Vecdec Mode 2: Generate Fault Vectors and Estimate Prob(Fail)

Source: https://github.com/qec-pages/vecdec/blob/main/README.md

Use mode 2 to generate likely fault vectors and estimate the probability of failure. Submodes allow for different estimation methods, including using average LLRs, exact greedy probability, or reference probability vectors. Parameters control the number of random information set steps, waiting steps, and the weight/energy of vectors to keep.

```sh
 mode=2 : Generate most likely fault vectors, estimate Prob(Fail).
	Submode bitmap values:
			 .1  (bit 0) calculate original fail probability estimate
			 .2  (bit 1) fail prob estimate using average LLRs and cw count
			 .4  (bit 2) calculate exact greedy probability estimate
			 .8  (bit 3) approx greedy prob estimate with prefactor
			 .16 (bit 4) use reference `refQ/finQ/useQ` to calculate fail
				 probability estimates (as opposed to direct summations)
	 Use up to 'steps' random information set (RIS) steps
	 unless no new codewords (fault vectors) have been found for 'swait' steps.
	 Use 'steps=0' to just use the codewords from the file 
	 With `dW>=0`, keep vectors of weight up to 'dW' above min weight found.
	 With `dE>=0`, keep vectors of energy up to 'dE' above minimum E found (sum of LLRs).
	 When 'maxC' is non-zero, generate up to 'maxC' unique codewords.
	 If 'outC' is set, write full list of CWs to this file.
	 If 'finC' is set, read initial set of CWs from this file.
	 Accuracy and performance are determined by parameters 
	 'steps' (number of RIS rounds), 'lerr' (OSD level, defaul=-1, no OSD).
	 Specify a single DEM file 'fdem', or 'finH', 'finL', and 'finP'
	 separately (either 'finL' or 'finG' is needed for a quantum code).
	 Use 'useP' to override error probability values in DEM file.   
	 Use 'mulP' to scale error probability values from DEM file.   
	 Similarly, use 'finQ' or 'useQ' arguments to specify alternative
	 probability vectors with mode 2.16
```

--------------------------------

### Generate Classical Codewords with Minimum Weight

Source: https://github.com/qec-pages/vecdec/blob/main/USAGE.adoc

Use mode=3 with dW=0 to generate classical codewords orthogonal to H, limiting them to the minimum weight found. This step is crucial for ensuring the generator matrix G has the smallest possible row weights.

```sh
vecdec --mode 3 --dW 0 --in ./examples/surf_d3.dem --out tmp
```

```sh
862 distinct vectors (minW=3)
```

--------------------------------

### Vecdec Seed Parameter Randomness Calculation

Source: https://github.com/qec-pages/vecdec/blob/main/README.md

Explains how the 'seed' parameter is used for randomness. When negative, it combines the provided value with `time(NULL)` and `getpid()` for enhanced randomness, following the formula `seed = x + time(NULL) + 1000000ul * getpid()`.

```C
seed = x + time(NULL) + 1000000ul * getpid();
```

--------------------------------

### Process Text Files with AWK and SED

Source: https://github.com/qec-pages/vecdec/blob/main/todo.md

Utility commands to mask characters in a file using AWK or SED.

```sh
awk '{print substr($0,1,5) gensub(/./,"*","g",substr($0,6))}'  tmpA.01
## SED to achieve the same :
sed -e 's/./*/g6' tmpA.01
```

--------------------------------

### Calculate Code Distance

Source: https://github.com/qec-pages/vecdec/blob/main/USAGE.adoc

Calculate the minimum weight of a code by setting dW=0 and skipping energy calculations.

```sh
include::examples/ex_D0.sh[]
```

```sh
include::examples/ex_D0_sh.out[]
```

--------------------------------

### Generate Error Data with Stim

Source: https://context7.com/qec-pages/vecdec/llms.txt

Use Stim to generate detector event and observable data for decoding. Specify the Detector Error Model (DEM) file and output formats.

```bash
stim sample_dem --shots 5000 --in ./examples/surf_d3.dem \
    --out tmp_det.01 --out_format 01 \
    --obs_out tmp_obs.01 --obs_out_format 01
```

--------------------------------

### Decode Using Stim-Generated Events

Source: https://github.com/qec-pages/vecdec/blob/main/USAGE.adoc

Samples detector and observable events from a DEM file and uses them for vecdec decoding.

```sh
stim=../Stim/out/stim
fnam=sd5
$stim sample_dem --shots 10240 --in $fnam.dem \
        --out $fnam.det --out_format 01 \
        --obs_out $fnam.obs --obs_out_format 01
$vecdec debug=1 mode=1.14 fdem=$fnam.dem fdet=$fnam.det fobs=$fnam.obs steps=50 lerr=2 \
           nvec=1024 ntot=10240
```

--------------------------------

### Increase pre-decoder parameter `uW` for faster decoding

Source: https://github.com/qec-pages/vecdec/blob/main/USAGE.adoc

Increasing the pre-decoder parameter `uW` can significantly speed up decoding without reducing accuracy, by handling more syndrome vectors in the pre-decoder stage.

```sh
vecdec --code ./examples/96.3.963.alist --steps 5000 --lerr 1 --uW 4 --seed 123
```

--------------------------------

### Vecdec Mode 1: Iterative Decoder

Source: https://github.com/qec-pages/vecdec/blob/main/README.md

Details on using the iterative decoder (mode 1) with various submodes, parameters, and error handling.

```APIDOC
## POST /vecdec mode=1

### Description
Uses one of several iterative decoder versions. This decoder may experience convergence issues. Accuracy and performance are determined by 'steps', 'lerr', and 'maxosd'. Using 'steps' not higher than 50 is recommended.

### Method
POST

### Endpoint
`/vecdec`

### Parameters
#### Query Parameters
- **mode** (float) - Required - Set to 1 for iterative decoder. Can include submode, e.g., `1.1`, `1.2`.
  - Submode bitmap values:
    - .1 (bit 0): Use regular LLR.
    - .2 (bit 1): Use average LLR (takes precedence).
    - .4 (bit 2): Use serial BP schedule (not parallel).
    - .8 (bit 3): With serial, use V-based order (not C-based).
    - .16 (bit 4): With serial, randomize node order in each round.
    - .32 (bit 5): With serial, suppress all node order randomization (requires bpretry=1 and bit 4 not set).
  - `submode=0` is equivalent to `submode=3`.
- **steps** (integer) - Optional - Number of BP rounds. Recommended not higher than 50.
- **lerr** (integer) - Optional - OSD level (default: -1, on OSD).
- **maxosd** (integer) - Optional - Number of columns for OSD in levels 2 and above.
- **bpgamma** (float) - Optional - Specifies how averaging is done (default: 0.5).
- **bpretry** (integer) - Optional - Number of times to retry BP (default: 1, do not retry).
- **qllr** (integer) - Optional - Parameters to set LLR quantization.
- **qllr2** (integer) - Optional - If 0, Sum-Product algorithm reduces to Min-Sum.
- **fdem** (string) - Optional - Path to a single DEM file.
- **finH** (string) - Optional - Path to input file for H matrix.
- **finL** (string) - Optional - Path to input file for L matrix (required for quantum codes if finG is not used).
- **finP** (string) - Optional - Path to input file for P matrix.
- **finG** (string) - Optional - Path to input file for G matrix (needed for quantum codes if finL is not used).
- **useP** (boolean) - Optional - Overrides error probability values in DEM file.
- **mulP** (float) - Optional - Scales error probability values from DEM file.
- **ferr** (string) - Optional - Path to a file containing errors (01 format).
- **fdet** (string) - Optional - Path to a file with detector events.
- **fobs** (string) - Optional - Path to a file with observables.
- **nfail** (integer) - Optional - For early termination.
- **swait** (integer) - Optional - For early termination.
- **ntot** (integer) - Optional - Total number of errors to read or generate.
- **nvec** (integer) - Optional - Number of errors to read or generate in chunks.
- **uW** (integer) - Optional - Use hash storage to speed up decoding (non-negative).
- **maxU** (integer) - Optional - Limit on the number of syndrome vectors in the hash (0 for no limit).
- **uR** (integer) - Optional - Limit on the v-v graph distance between non-zero positions in stored error vectors (0 for no limit).
- **uX** (integer) - Optional - Bitmap for experimental cluster-based predecoder options (default: 0). Use with caution.

### Request Example
```json
{
  "mode": 1.1,
  "steps": 50,
  "lerr": 3,
  "finH": "path/to/code.H",
  "finL": "path/to/code.L"
}
```

### Response
#### Success Response (200)
- **status** (string) - Decoding status message.
- **decoded_errors** (integer) - Number of errors decoded.

#### Response Example
```json
{
  "status": "Decoding successful",
  "decoded_errors": 10
}
```
```

--------------------------------

### Enumerate Codewords and Estimate LER

Source: https://github.com/qec-pages/vecdec/blob/main/USAGE.adoc

Use RIS algorithm to enumerate codewords and estimate logical error rates, optionally exporting results to a file.

```sh
include::examples/ex_D1.sh[]
```

```sh
include::examples/ex_D1_sh.out[]
```

```sh
include::examples/ex_D2.sh[]
```

```sh
include::examples/ex_D2_sh.out[lines="10..-1"]
```

```sh
include::examples/ex_D3.sh[]
```

```sh
include::examples/ex_D3_sh.out[]
```

```sh
include::examples/ex_D4.sh[]
```

```sh
include::examples/ex_D4_sh.out[]
```

```sh
include::examples/ex_D5.sh[]
```

```sh
include::examples/ex_D5_sh.out[lines="30..-1"]
```

--------------------------------

### Generate Generator Matrix G with Limited Row Weights

Source: https://github.com/qec-pages/vecdec/blob/main/USAGE.adoc

Generate the generator matrix G (Hx) using explicit maxW=3 to limit row weights. This ensures the logical generator matrix has the correct number of rows.

```sh
vecdec --mode 3 --dW 0 --maxW 3 --in ./examples/surf_d3.dem --out tmpG
```

```sh
726 rows
```

--------------------------------

### Export Code Matrices

Source: https://context7.com/qec-pages/vecdec/llms.txt

Parses a DEM file and exports the H, G, L, and K matrices along with the probability vector in Matrix Market format.

```bash
# Export matrices from DEM file
./src/vecdec mode=3 fdem=./examples/surf_d3.dem fout=tmp
```