Add docs for AI decoder training with PyTorch

[wsttiger]

Add TensorRT Decoder Training Tutorial

Overview

This PR introduces comprehensive documentation for training and deploying neural network-based quantum error correction decoders using the TensorRT decoder plugin (trt_decoder), which is being released with CUDA-Q QEC v0.5.0.

Motivation

With the release of the TensorRT decoder, users need clear guidance on:

• How to generate training data for QEC decoding tasks
• How to train custom neural network decoders
• How to export models to ONNX format
• How to deploy trained models with TensorRT for accelerated GPU inference

This tutorial provides an end-to-end workflow demonstrating the complete pipeline from data generation to production deployment.

Changes Made

New Documentation

• training_ai_decoders.rst: Comprehensive tutorial covering:
  • Training neural network decoders with PyTorch and Stim
  • Surface code circuit generation and data sampling
  • MLP architecture design and training workflow
  • ONNX model export
  • TensorRT deployment with Python and C++ examples
  • Converting ONNX models to TensorRT engines using trtexec
  • Performance tuning and best practices

Training Script

• train_mlp_decoder.py: Complete working example demonstrating:
  • Stim-based synthetic data generation for surface codes
  • PyTorch MLP decoder implementation
  • Training loop with validation and early stopping
  • ONNX export for TensorRT deployment
  • Moved from unittest directory to docs/sphinx/examples/qec/python/

Documentation Updates

• examples.rst: Added new tutorial to QEC examples table of contents
• decoders.rst: Minor formatting cleanup

Tutorial Features

• ✅ Complete end-to-end workflow from training to deployment
• ✅ Both Python and C++ usage examples
• ✅ Multiple precision modes (fp16, fp32, bf16, int8, fp8, tf32, best)
• ✅ Production deployment guidance with pre-built TensorRT engines
• ✅ Best practices and performance tuning tips
• ✅ Clear dependency requirements

Target Audience

• Users training custom neural network decoders for QEC
• Researchers experimenting with ML-based decoding approaches
• Developers deploying production QEC systems with TensorRT acceleration

Testing

The training script has been tested and successfully:

• Generates training data using Stim
• Trains an MLP decoder on surface code syndromes
• Exports models to ONNX format compatible with TensorRT
• Achieves convergence with validation accuracy monitoring

---

Related Components:

• TensorRT decoder plugin (PR Add trt decoder #307)
• CUDA-Q QEC library decoder interface

[bmhowe23]

@wsttiger regarding the CI failures, what is the plan? Do the CI runners need an extra package installed? If so, can you add the package to the runners as part of this PR?

[wsttiger]

/ok to test 3e3ecc1

[bmhowe23]

Approved, but let's hold off on merging until the release is done.