fix: handle disconnected components in tropical TN contraction (#70)

* feat: add tropical tensor network threshold analysis script

Add scripts/analyze_tropical_threshold.py for analyzing the threshold of
tropical tensor network MAP decoder on rotated surface codes.

Key features:
- Builds UAI factor graph from DEM parity check matrix
- Uses tropical tensor network contraction for exact MAP inference
- Computes observable prediction using mod-2 arithmetic with obs_flip thresholding
- Generates threshold plots comparing LER across error rates

Known limitation: MAP decoding finds the single most likely error pattern,
but QEC requires the most likely observable value. This causes ~2x higher
LER compared to BP+OSD which uses marginal probabilities. See issue for
discussion of potential improvements.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix: handle disconnected components in tropical TN contraction

The tropical TN decoder was producing incorrect results because
omeco.optimize_code only processes one connected component of the
factor graph. When prior factors (single-variable) were disconnected
from constraint factors, they were being dropped from the contraction
tree.

Changes:
- Add _find_connected_components() using union-find algorithm
- Modify get_omeco_tree() to handle multiple disconnected components
- Update analyze_tropical_threshold.py to use pymatching graph structure
- Add comprehensive tests for connected components handling
- Add tests verifying Tropical TN matches MWPM on surface codes

Fixes #68

* refactor: use bpdecoderplus.dem instead of pymatching for tropical TN

Update analyze_tropical_threshold.py and tests to use build_parity_check_matrix
from bpdecoderplus.dem instead of pymatching's graph structure:

- Use merge_hyperedges=True for efficient computation (smaller matrix)
- Threshold obs_flip at 0.5 for soft values from hyperedge merging
- Remove pymatching dependency from core decoder (optional for comparison)
- Update tests to use bpdecoderplus.dem functions

The connected components fix ensures all factors are included in the
contraction tree regardless of the matrix construction method.

* Debug the tropical tensor network

* docs: improve documentation with LaTeX math and benchmark results

- Add MathJax support via pymdownx.arithmatex extension
- Create mathjax.js config for proper math rendering
- Convert mathematical_description.md to use proper LaTeX notation
- Add benchmark results section to getting_started.md
- Include threshold plots and decoder comparison images

Closes #69

* fix: address PR review comments for tropical TN

- Fix empty detector handling in test_tropical_fix.py to check syndrome
- Convert combine_trees from recursive to iterative to avoid recursion limits
- Add validation to get_output_vars for better error messages
- Remove unused imports (pytest, torch) in test files
- Remove unused observables variable in test_tropical_mwpm_match.py

All 123 tests pass.

* test: add tests for build_decoding_uai to improve coverage

Add TestBuildDecodingUAI class with 6 tests:
- test_basic_uai_structure: verify UAI header format
- test_prior_factors: check prior probability values
- test_constraint_factors_syndrome_zero: even parity constraints
- test_constraint_factors_syndrome_one: odd parity constraints
- test_empty_detector: handle detectors with no connected errors
- test_real_surface_code: integration test with real DEM

This improves code coverage for the new build_decoding_uai function.

* test: increase code coverage from 95% to 97%

Add additional tests for better coverage:

- test_dem.py: Add tests for zero-probability errors and no-split mode
- test_cli.py: Add tests for --generate-dem and --generate-syndromes flags
- test_syndrome.py: Add tests for metadata edge cases (0-dim array, dict)
- test_uai_parser.py: Add tests for Factor/UAIModel repr and empty evidence

Total: 141 tests passing with 97% coverage.

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: ChanceSiyuan

docs/getting_started.md

@@ -428,6 +428,48 @@ A: Use UAI format if you want to:
 - Perform exact inference or marginal probability calculations
 - Use tensor network methods for decoding
 
+## Benchmark Results
+
+This section shows the performance benchmarks for the decoders included in BPDecoderPlus.
+
+### Decoder Threshold Comparison
+
+The threshold is the physical error rate below which increasing the code distance reduces the logical error rate. Our benchmarks compare BP and BP+OSD decoders:
+
+![Threshold Plot](images/threshold_plot.png)
+
+The threshold plot shows logical error rate vs physical error rate for different code distances. Lines that cross indicate the threshold point.
+
+### BP vs BP+OSD Comparison
+
+![Threshold Comparison](images/threshold_comparison.png)
+
+BP+OSD (Ordered Statistics Decoding) significantly improves upon standard BP, especially near the threshold region.
+
+### Decoding Examples
+
+**BP Failure Case:**
+
+![BP Failure Demo](images/bp_failure_demo.png)
+
+This shows a case where standard BP fails to find the correct error pattern.
+
+**OSD Success Case:**
+
+![OSD Success Demo](images/osd_success_demo.png)
+
+The same syndrome decoded successfully with BP+OSD post-processing.
+
+### Benchmark Summary
+
+| Decoder | Threshold (approx.) | Notes |
+|---------|---------------------|-------|
+| BP (damped) | ~8% | Fast, but limited by graph loops |
+| BP+OSD | ~10% | Higher threshold, slightly slower |
+| MWPM (reference) | ~10.3% | Gold standard for comparison |
+
+The BP+OSD decoder achieves near-MWPM performance while being more scalable to larger codes.
+
 ## Next Steps
 
 1. **Generate your first dataset** using the Quick Start command

docs/images/bp_failure_demo.png

@@ -0,0 +1,8 @@
+window.MathJax = {
+  tex: {
+    inlineMath: [["\\(", "\\)"]],
+    displayMath: [["\\[", "\\]"]],
+    processEscapes: true,
+    processEnvironments: true
+  }
+};

docs/images/osd_success_demo.png

@@ -7,35 +7,53 @@ See https://github.com/TensorBFS/TensorInference.jl for the Julia reference.
 
 ### Factor Graph Notation
 
-- Variables are indexed by x_i with domain size d_i.
-- Factors are indexed by f and connect a subset of variables.
-- Each factor has a tensor (potential) phi_f defined over its variables.
+- Variables are indexed by \(x_i\) with domain size \(d_i\).
+- Factors are indexed by \(f\) and connect a subset of variables.
+- Each factor has a tensor (potential) \(\phi_f\) defined over its variables.
 
 ### Messages
 
-Factor to variable message:
+**Factor to variable message:**
 
-mu_{f->x}(x) = sum_{all y in ne(f), y != x} phi_f(x, y, ...) * product_{y != x} mu_{y->f}(y)
+\[
+\mu_{f \to x}(x) = \sum_{\{y \in \text{ne}(f), y \neq x\}} \phi_f(x, y, \ldots) \prod_{y \neq x} \mu_{y \to f}(y)
+\]
 
-Variable to factor message:
+**Variable to factor message:**
 
-mu_{x->f}(x) = product_{g in ne(x), g != f} mu_{g->x}(x)
+\[
+\mu_{x \to f}(x) = \prod_{g \in \text{ne}(x), g \neq f} \mu_{g \to x}(x)
+\]
 
 ### Damping
 
 To improve stability on loopy graphs, a damping update is applied:
 
-mu_new = damping * mu_old + (1 - damping) * mu_candidate
+\[
+\mu_{\text{new}} = \alpha \cdot \mu_{\text{old}} + (1 - \alpha) \cdot \mu_{\text{candidate}}
+\]
+
+where \(\alpha\) is the damping factor (typically between 0 and 1).
 
 ### Convergence
 
-We use an L1 difference threshold between consecutive factor->variable
-messages to determine convergence.
+We use an \(L_1\) difference threshold between consecutive factor-to-variable
+messages to determine convergence:
+
+\[
+\max_{f,x} \| \mu_{f \to x}^{(t)} - \mu_{f \to x}^{(t-1)} \|_1 < \epsilon
+\]
 
 ### Marginals
 
 After convergence, variable marginals are computed as:
 
-b(x) = (1 / Z) * product_{f in ne(x)} mu_{f->x}(x)
+\[
+b(x) = \frac{1}{Z} \prod_{f \in \text{ne}(x)} \mu_{f \to x}(x)
+\]
+
+The normalization constant \(Z\) is obtained by summing the unnormalized vector:
 
-The normalization constant Z is obtained by summing the unnormalized vector.
+\[
+Z = \sum_x \prod_{f \in \text{ne}(x)} \mu_{f \to x}(x)
+\]

docs/images/threshold_comparison.png

@@ -47,6 +47,12 @@ markdown_extensions:
   - pymdownx.details
   - attr_list
   - md_in_html
+  - pymdownx.arithmatex:
+      generic: true
+
+extra_javascript:
+  - javascripts/mathjax.js
+  - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js
 
 nav:
   - Home: index.md