[SpinGlassPEPS 6/6] Add PEPS backend docs, examples, and benchmark scripts

[bernalde]

Stack position

6 of 6. This PR should be based on the QUBODrivers/JuMP exposure PR.

Goal

Add documentation, examples, and benchmark coverage that make it clear when the PEPS backend should be used, how it compares to the current DMRG backend, and what limitations come from the SpinGlassPEPS paper.

Context

The integration should not imply that SpinGlassPEPS supersedes TenSolver. The paper reports that the PEPS branch-and-bound approach is useful for structured quasi-2D Ising/Potts problems but has stability/performance limitations on large random Pegasus/Zephyr instances. It can be competitive or better on simpler square/king-style lattices and some planted/tile-style instances.

Docs and benchmarks should set user expectations correctly.

Documentation tasks

Add or update docs covering:

1. Backend overview

   • DMRG backend: default, general QUBO/PUBO path.
   • PEPS backend: optional, experimental, structured quasi-2D path.

2. Installation

   • Explain any optional extension or bridge package installation.
   • Note Julia compatibility requirements if the PEPS bridge requires Julia 1.11.
   • Note GPU dependencies are optional and not required for small CPU tests.

3. Supported topologies

   • square grid
   • king grid
   • Pegasus if implemented
   • Zephyr if implemented

4. Usage examples

   • direct Julia API example for a small square grid
   • JuMP/QUBODrivers example selecting backend = :peps
   • metadata inspection example

5. Parameter guide

   • beta: higher values sharpen low-energy resolution but can destabilize contraction.
   • bond_dim: larger boundary MPS bond dimension can improve contraction but increases cost.
   • max_states: branch-and-bound width.
   • cutoff_prob: pruning threshold.
   • transformations: trying lattice rotations/reflections can improve results.
   • truncation/local dimension reduction: can reduce cost but may remove globally optimal configurations.

6. Limitations

   • PEPS is not appropriate for arbitrary dense QUBOs.
   • Approximate contraction can fail.
   • Randomized SVD/zipper methods may introduce run-to-run variability.
   • GPU memory can limit feasible bond dimensions on Pegasus/Zephyr.
   • Current TenSolver DMRG remains the default general-purpose backend.

Benchmark tasks

Add reproducible benchmark scripts under a non-CI path, for example:

• benchmarks/peps_square.jl
• benchmarks/peps_king.jl
• benchmarks/peps_pegasus_small.jl if Pegasus support exists

Benchmarks should compare:

• TenSolver DMRG backend
• PEPS backend
• brute force for tiny instances only

Metrics:

• best objective value
• objective gap from brute force when available
• runtime
• number of returned states
• PEPS metadata such as largest discarded probability and selected transformation

Keep benchmark scripts deterministic where possible:

• set random seeds
• use CPU defaults unless explicitly testing GPU
• clearly annotate expected runtime

Tests

Do not add long benchmarks to normal CI.

Add lightweight doc or smoke tests only:

• small example runs within a short time budget
• PEPS examples gated if optional dependency is unavailable
• DMRG docs continue to run without optional PEPS dependencies

Acceptance criteria

• Docs explain backend selection and limitations clearly.
• At least one direct API PEPS example is documented.
• At least one JuMP/QUBODrivers PEPS example is documented if PR 5 implemented that path.
• Benchmark scripts exist but are not part of default CI.
• Existing docs for the DMRG backend remain accurate.

Out of scope

• Claiming performance superiority.
• Reproducing the full arXiv benchmark suite.
• Requiring CUDA in normal CI.

[bernalde]

Branch hygiene note for PR automation:

This issue is part of the SpinGlassPEPS sequence, but the PR should not be treated as ready while it is stacked on an experimental branch.

Current PR: #46 (docs/issue-40-peps-examples-benchmarks), currently based on feature/issue-39-jump-peps-attrs.

Before marking this issue's PR ready, first resolve the prerequisite issue/PR #39 / #45. After that prerequisite lands, rebase or recreate this branch from current origin/main and set the PR base to main.

When updating or recreating the PR body, include a Branch Hygiene section with:

• Base branch: main
• Created/rebased from: origin/main
• Stacked on experimental branch: no
• Prerequisite parked branches: Add JuMP PEPS backend attributes #45 merged / closed / superseded