TensorBFS · ChanceSiyuan · Jan 25, 2026 · Jan 20, 2026
diff --git a/README.md b/README.md
@@ -171,6 +171,24 @@ python examples/evidence_example.py
 python examples/minimal_example.py
 ```
 
+### Tanner Graph Decoding Tutorial
+
+For a comprehensive walkthrough of using Belief Propagation on Tanner graphs for surface code decoding, see the [Tanner Graph Walkthrough](https://giggleliu.github.io/BPDecoderPlus/tanner_graph_walkthrough/) documentation.
+
+The walkthrough covers:
+
+- **Tanner graph theory** - Bipartite graph representation of parity check codes
+- **Complete decoding pipeline** - From circuit generation to BP decoding and evaluation
+- **Visualization** - Interactive graph structures and convergence analysis
+- **Parameter tuning** - Damping, tolerance, and iteration optimization
+- **Hands-on examples** - Runnable code with d=3 surface code datasets
+
+**Run the companion script:**
+
+```bash
+uv run python examples/tanner_graph_walkthrough.py
+```
+
 ## Project Structure
 
 ```

diff --git a/docs/images/tanner_graph/adjacency_matrix.png b/docs/images/tanner_graph/adjacency_matrix.png
diff --git a/docs/images/tanner_graph/convergence_analysis.png b/docs/images/tanner_graph/convergence_analysis.png
diff --git a/docs/images/tanner_graph/damping_comparison.png b/docs/images/tanner_graph/damping_comparison.png
diff --git a/docs/images/tanner_graph/degree_distribution.png b/docs/images/tanner_graph/degree_distribution.png
diff --git a/docs/images/tanner_graph/tanner_graph_full.png b/docs/images/tanner_graph/tanner_graph_full.png
diff --git a/docs/images/tanner_graph/tanner_graph_subgraph.png b/docs/images/tanner_graph/tanner_graph_subgraph.png