From 5a72bdcb9396802a9cf977d45fc99cb735bdb3b6 Mon Sep 17 00:00:00 2001 From: Ben Howe Date: Mon, 6 Apr 2026 12:47:41 -0700 Subject: [PATCH 1/3] DISTANCE and N_ROUNDS updates Signed-off-by: Ben Howe --- README.md | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index a0b398b..3266f1d 100644 --- a/README.md +++ b/README.md @@ -138,8 +138,16 @@ The pre-trained public models use `--model-id 1` (R=9) and `--model-id 4` (R=13) After training (or starting from the shipped `.safetensors` files), you can export the model to ONNX and optionally apply INT8 or FP8 post-training quantization for deployment. -Set the `ONNX_WORKFLOW` and (optionally) `QUANT_FORMAT` environment variables before running -inference with `local_run.sh`: +You may also change the surface code distance and number of rounds at inference +time. That is - you are not required retrain a new model when changing either +one of these parameters; since the model is a 3D convolutional neural network, +the model will simply be run over a new decoding volume. + +- To run with a new distance, simply add `DISTANCE=` to the commands below. +- To run with a new number of rounds, simply add `N_ROUNDS=` to the commands below. + +Set the `ONNX_WORKFLOW` and (optionally) (`QUANT_FORMAT`, `DISTANCE`, +`N_ROUNDS`) environment variables before running inference with `local_run.sh`: | `ONNX_WORKFLOW` | Behavior | |---|---| @@ -169,7 +177,16 @@ ONNX_WORKFLOW=3 WORKFLOW=inference bash code/scripts/local_run.sh | `QUANT_FORMAT` | unset | `int8` or `fp8`. Unset means no quantization (FP32 ONNX). | | `QUANT_CALIB_SAMPLES` | `256` | Calibration samples for INT8/FP8 post-training quantization. | +**Circuit variables:** + +| Variable | Default | Description | +|---|---|---| +| `CONFIG_NAME` | `config_public` | Use the defaults from the `conf/$CONFIG_NAME.yaml` file | +| `DISTANCE` | Use the distance specified in the `conf/$CONFIG_NAME.yaml` file | surface code distance | +| `N_ROUNDS` | Calibration samples for INT8/FP8 post-training quantization. | number of rounds in memory experiment | + Notes: + - TensorRT workflows (`ONNX_WORKFLOW=2` or `3`) require `tensorrt` and `modelopt`. - FP8 quantization failure is fatal. INT8 failure falls back to the FP32 ONNX model silently. - ONNX and engine files are written to the current working directory. @@ -215,7 +232,7 @@ Results are written to `outputs//plots/`. | Decoder | Source | Notes | |---|---|---| | No-op | — | Pre-decoder output only, no global correction | -| Union-Find | `ldpc` | Fast, sub-optimal | +| Union-Find | `ldpc` | Fast, sub-optimal LER (Logical Error Rate) | | BP-only | `ldpc` | Belief propagation, no OSD | | BP+LSD-0 | `ldpc` | BP with localized statistics decoding | | Uncorr-PM | PyMatching | Uncorrelated minimum-weight perfect matching | From 757f378b9eb6029207f6a621cb26f77f8c4b5b48 Mon Sep 17 00:00:00 2001 From: Ben Howe Date: Mon, 6 Apr 2026 12:47:56 -0700 Subject: [PATCH 2/3] Formatting updates Signed-off-by: Ben Howe --- README.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 3266f1d..9772f8a 100644 --- a/README.md +++ b/README.md @@ -61,6 +61,7 @@ WORKFLOW=inference bash code/scripts/local_run.sh ``` Inference note: + - On bare metal, keep the default DataLoader workers. - In containers, set a larger shared-memory size (e.g., `docker run --shm-size=1g ...`). - If you cannot change `--shm-size`, set `PREDECODER_INFERENCE_NUM_WORKERS=0` to avoid shared-memory worker crashes. @@ -83,6 +84,7 @@ Inference note: If you are not training locally, you can run inference using pre-trained models. 1. **(Optional) create a venv and install inference deps**: + ```bash python -m venv .venv source .venv/bin/activate @@ -90,18 +92,20 @@ python -m pip install --upgrade pip pip install -r code/requirements_public_inference.txt ``` -2. **Get the pre-trained models** +1. **Get the pre-trained models** This repo ships two pre-trained model files (tracked with Git LFS): - `models/PreDecoderModelMemory_r9_v1.0.77.pt` (receptive field R=9, checkpoint 77) - `models/PreDecoderModelMemory_r13_v1.0.86.pt` (receptive field R=13, checkpoint 86) Clones get the files via `git lfs pull`. Optionally, set `PREDECODER_MODEL_URL` to the LFS/raw URL to fetch files when not in the working tree (e.g. in a minimal checkout or CI). -3. Set: +2. Set: + - `EXPERIMENT_NAME=predecoder_model_1` - `model_id: 1` in `conf/config_public.yaml` -4. **Run inference**: +1. **Run inference**: + ```bash WORKFLOW=inference EXPERIMENT_NAME=predecoder_model_1 bash code/scripts/local_run.sh ``` @@ -387,8 +391,6 @@ LOGICAL Z (lz): ● · · ``` - - #### Noise model (public default) - `data.noise_model`: a **25-parameter circuit-level** noise model (SPAM, idles, and CNOT Pauli channels). @@ -441,7 +443,6 @@ Either method causes the training pipeline to use the user-specified noise model [Train] noise_model upscaling SKIPPED (skip_noise_upscaling=true or PREDECODER_SKIP_NOISE_UPSCALING=1). ``` - ### Precomputed frames (recommended) Training/validation data generation can load precomputed frames from: @@ -456,11 +457,9 @@ python3 code/data/precompute_frames.py --distance 13 --n_rounds 13 --basis X Z - ### Resuming training & running inference on a trained model - - **Inference uses the trained model from `outputs//models/`**, so keep the same `EXPERIMENT_NAME` when you switch from training to inference. - **Training auto-resumes**: if a run is interrupted, launching the same training command again (same `EXPERIMENT_NAME`) will automatically load the latest checkpoint it finds and continue training (up to the fixed 100 epochs). To force a clean restart, set `FRESH_START=1`, although we recommend changing `EXPERIMENT_NAME` instead. - ### What gets written where Runs are organized under: @@ -520,6 +519,7 @@ PYTHONPATH=code python -m unittest discover -s code/tests -p "test_*.py" ``` Useful env vars for noise model tests: + - `RUN_SLOW=1` enables >=100k-shot statistical tests - `NOISEMODEL_FAST_SHOTS` controls fast-tier shots (default 10000) - `NOISEMODEL_SLOW_SHOTS` controls slow-tier shots (default 100000) @@ -573,4 +573,4 @@ Presence of these headers is enforced automatically by the `spdx-header-check` C `.github/workflows/ci.yml`). Third-party open source components bundled with or required by this project are listed with their -respective copyright notices and license texts in [NOTICE](NOTICE). \ No newline at end of file +respective copyright notices and license texts in [NOTICE](NOTICE). From 9405ca6cdfcf95dbc5c2e223698565082b0045a2 Mon Sep 17 00:00:00 2001 From: Ben Howe Date: Mon, 6 Apr 2026 12:52:03 -0700 Subject: [PATCH 3/3] Revert "Formatting updates" This reverts commit 757f378b9eb6029207f6a621cb26f77f8c4b5b48. --- README.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 9772f8a..3266f1d 100644 --- a/README.md +++ b/README.md @@ -61,7 +61,6 @@ WORKFLOW=inference bash code/scripts/local_run.sh ``` Inference note: - - On bare metal, keep the default DataLoader workers. - In containers, set a larger shared-memory size (e.g., `docker run --shm-size=1g ...`). - If you cannot change `--shm-size`, set `PREDECODER_INFERENCE_NUM_WORKERS=0` to avoid shared-memory worker crashes. @@ -84,7 +83,6 @@ Inference note: If you are not training locally, you can run inference using pre-trained models. 1. **(Optional) create a venv and install inference deps**: - ```bash python -m venv .venv source .venv/bin/activate @@ -92,20 +90,18 @@ python -m pip install --upgrade pip pip install -r code/requirements_public_inference.txt ``` -1. **Get the pre-trained models** +2. **Get the pre-trained models** This repo ships two pre-trained model files (tracked with Git LFS): - `models/PreDecoderModelMemory_r9_v1.0.77.pt` (receptive field R=9, checkpoint 77) - `models/PreDecoderModelMemory_r13_v1.0.86.pt` (receptive field R=13, checkpoint 86) Clones get the files via `git lfs pull`. Optionally, set `PREDECODER_MODEL_URL` to the LFS/raw URL to fetch files when not in the working tree (e.g. in a minimal checkout or CI). -2. Set: - +3. Set: - `EXPERIMENT_NAME=predecoder_model_1` - `model_id: 1` in `conf/config_public.yaml` -1. **Run inference**: - +4. **Run inference**: ```bash WORKFLOW=inference EXPERIMENT_NAME=predecoder_model_1 bash code/scripts/local_run.sh ``` @@ -391,6 +387,8 @@ LOGICAL Z (lz): ● · · ``` + + #### Noise model (public default) - `data.noise_model`: a **25-parameter circuit-level** noise model (SPAM, idles, and CNOT Pauli channels). @@ -443,6 +441,7 @@ Either method causes the training pipeline to use the user-specified noise model [Train] noise_model upscaling SKIPPED (skip_noise_upscaling=true or PREDECODER_SKIP_NOISE_UPSCALING=1). ``` + ### Precomputed frames (recommended) Training/validation data generation can load precomputed frames from: @@ -457,9 +456,11 @@ python3 code/data/precompute_frames.py --distance 13 --n_rounds 13 --basis X Z - ### Resuming training & running inference on a trained model + - **Inference uses the trained model from `outputs//models/`**, so keep the same `EXPERIMENT_NAME` when you switch from training to inference. - **Training auto-resumes**: if a run is interrupted, launching the same training command again (same `EXPERIMENT_NAME`) will automatically load the latest checkpoint it finds and continue training (up to the fixed 100 epochs). To force a clean restart, set `FRESH_START=1`, although we recommend changing `EXPERIMENT_NAME` instead. + ### What gets written where Runs are organized under: @@ -519,7 +520,6 @@ PYTHONPATH=code python -m unittest discover -s code/tests -p "test_*.py" ``` Useful env vars for noise model tests: - - `RUN_SLOW=1` enables >=100k-shot statistical tests - `NOISEMODEL_FAST_SHOTS` controls fast-tier shots (default 10000) - `NOISEMODEL_SLOW_SHOTS` controls slow-tier shots (default 100000) @@ -573,4 +573,4 @@ Presence of these headers is enforced automatically by the `spdx-header-check` C `.github/workflows/ci.yml`). Third-party open source components bundled with or required by this project are listed with their -respective copyright notices and license texts in [NOTICE](NOTICE). +respective copyright notices and license texts in [NOTICE](NOTICE). \ No newline at end of file