nvidia/Ising-Decoder-ColorCode-1-Fast

Ising-Decoder-ColorCode-1-Fast Overview

 

Description:

Ising-Decoder-ColorCode-1-Fast predicts physical space-time corrections that sparsify the input syndrome (producing a residual syndrome) for triangular color-code quantum error correction circuits, reducing logical error rates by at least 2x when combined with a standard global color-code decoder. Ising-Decoder-ColorCode-1-Fast v0.1.0 was developed by NVIDIA.

This model is ready for commercial or non-commercial use.

Publication

This implementation accompanies the paper:

Jan Olle, Christopher Chamberland, Muyuan Li, Igor Baratta, "Fast and accurate AI-based pre-decoders for color codes" arXiv:2607.10058, 2026. doi:10.48550/arXiv.2607.10058

Please cite the paper if you use this repository in research or published work.

License/Terms of Use:

GOVERNING TERMS: Use of this model is governed by the [OpenMDW-1.1 License](License.md).

Deployment Geography:

Global

Use Case:

Quantum computing researchers and engineers building triangular color-code QEC systems who need a lightweight predecoder to reduce logical error rates and accelerate decoding throughput alongside any standard global color-code decoder (we use Chromobius as an open-source example).

Release Date:

Hugging Face 07/21/2026 via https://huggingface.co/nvidia/Ising-Decoder-ColorCode-1-Fast

Reference(s):

• NVIDIA Quantum Predecoder
• Chromobius color-code decoder

Model Architecture:

Architecture Type: Convolutional Neural Network (CNN)

Network Architecture: Custom 3D CNN — bottleneck residual cascade of same-padded 3D convolutions (predecoder_memory_cascade)

Number of model parameters: ~2.94x10^6 (2,936,580)

The pre-decoder is a lightweight 3D fully-convolutional neural network (CNN) that processes color-code syndrome volumes across space and time.

Layers The network is a bottleneck residual cascade of same-padded 3D convolutions (padding = kernel_size // 2), so the spatial and temporal dimensions are preserved through every layer. A plain 3D-convolution stem lifts the 4 input channels to an embedding width of 512; a cascade of residual bottleneck blocks (bottleneck ratio 4, i.e. a 128-wide inner projection) then operates at that width, and a final 3D-convolution head projects back to 4 output channels. Each residual bottleneck block applies a pre-activation BatchNorm3d → SiLU pair before each of its three convolutions (the 1×1×1 reduce, the k×k×k message-passing, and the 1×1×1 restore), so the released checkpoint carries the corresponding BatchNorm parameters and running statistics; the plain input stem has no batch normalization. Dropout (p = 0.01) is applied inside the cascade.

| Checkpoint | Stem | num_blocks | Embedding width | Bottleneck ratio | Kernel size | Receptive field | |---------------------------|---------------------|------------|-----------------|------------------|-------------|-----------------| | ColorCode-1-Fast (d=13) * | plain Conv3d 4->512 | 6 | 512 | 4 | 3x3x3 | R = 13 |

(* this checkpoint)

Activation SiLU. The predecoder_memory_cascade architecture uses SiLU internally; the training-time activation config field is inert for this model.

Parameter count (approximate)

• ColorCode-1-Fast (this checkpoint): ~2.94 M parameters (2,936,580)

Precision The released checkpoint is stored in fp16 (half precision); the runner automatically sets cfg.enable_fp16 = True on load. (Training was performed in fp32 — see the Training Configuration section.)

Input(s):

Input Type(s): Quantum Error Correction Syndrome Tensor

Input Format(s):

• Tensor: float32 NumPy array or PyTorch tensor of shape (B, 4, T, H, W)

Input Parameters: Five-Dimensional (5D) — (Batch, Channels, Time, Height, Width)

Other Properties Related to Input:

• Shape: (B, 4, T, H, W) — batch x 4 syndrome channels x T rounds x an H x W rectangular embedding of the triangular color-code lattice, with H = d + (d − 1) // 2 rows and W = d columns for code distance d. Example: d = 13, T = 13 → (B, 4, 13, 19, 13)

• The 4 channels encode the X- and Z-basis color-code detector data (color partitions of the triangular color code) over the space-time syndrome volume

• dtype: float32 (cast to fp16 internally at inference time)

• Range: binary {0, 1} per element — 0 = no syndrome, 1 = detector fired

• Constraints: d and T may exceed the receptive field (RF = 13) — because the network is fully convolutional, a single d=13 checkpoint is evaluated at distances up to d=31 (H and W scale with d as above); training used d = T = 13 (distance == RF), which gave the best performance

• The network is fully convolutional and does not validate the spatial embedding: a tensor with a different spatial shape (e.g. a square d x d grid) is accepted silently and produces incorrectly mapped predictions. Always build inputs with the H x W embedding above (the repository's data generator emits it)

• The circuit must be a triangular color code using the superdense (nearest-neighbor) circuit schedule with Z feed-forward, consistent with the training distribution

• The noise model must be a circuit-level depolarizing channel consistent with the training distribution

Output(s)

Output Type(s): Quantum Error Correction Prediction Tensor

Output Format(s):

• Tensor: PyTorch tensor of shape (B, 4, T, H, W); dtype matches the checkpoint precision — fp16 for the released checkpoint

Output Parameters: Five-Dimensional (5D) — (Batch, Channels, Time, Height, Width)

Other Properties Related to Output:

• Shape: (B, 4, T, H, W) — same shape as input

• 4 correction channels: predicted space-time physical corrections (X- and Z-basis detector predictions across the color partitions) per lattice site and round

• dtype: precision-dependent logits — the released fp16 checkpoint returns fp16 logits (the evaluation path...