[SpinGlassPEPS 1/6] Document integration architecture and backend boundary

[bernalde]

Stack position

1 of 6. This is the base PR for the SpinGlassPEPS integration stack.

Goal

Add a short architecture/design document that records how TenSolver should integrate work from SpinGlassPEPS.jl and arXiv:2411.16431 without making SpinGlassPEPS a hard dependency or changing current solver behavior.

This PR should be documentation-only. It should make the intended integration reviewable before code introduces new dependencies, APIs, or solver paths.

Context

TenSolver currently exposes a compact QUBO/PUBO interface, tensorizes objectives into an ITensor MPO, and solves with 1D MPS/DMRG. It also provides a QUBODrivers/JuMP-facing optimizer.

SpinGlassPEPS.jl is not just a drop-in replacement for that flow. The repository itself is an umbrella package that reexports:

• SpinGlassNetworks
• SpinGlassEngine
• SpinGlassTensors
• SpinGlassExhaustive

The relevant algorithm from arXiv:2411.16431 is a finite-temperature PEPS representation of a Boltzmann distribution plus boundary-MPS contraction and branch-and-bound search over clustered Potts variables. It is particularly targeted at quasi-2D Ising/Potts factor graphs such as square, king, Pegasus, and Zephyr layouts.

The integration should therefore be treated as an optional structured-graph backend, not as a replacement for TenSolver's current DMRG backend.

Implementation details

Create a design document, for example:

• docs/src/spinglasspeps_integration.md, or
• docs/src/internals/spinglasspeps_backend.md if an internals section is preferred.

The document should cover:

1. Solver boundary

   • Current TenSolver backend: ITensor MPO + DMRG over Boolean variables.
   • Proposed PEPS backend: SpinGlassPEPS-style PEPS contraction + branch-and-bound over clustered Ising/Potts variables.
   • The default backend remains current TenSolver DMRG.

2. Supported problem classes

   • Current backend: general QUBO/PUBO, arbitrary variable ordering.
   • PEPS backend: structured Ising/Potts graphs that can be embedded into supported quasi-2D layouts.
   • Initial supported layouts should be square grid and king grid before Pegasus/Zephyr.
   • Pegasus/Zephyr should be treated as later, GPU-sensitive targets.

3. Dependency policy

   • Do not add SpinGlassPEPS or its component packages as hard dependencies in the first implementation.
   • Prefer a Julia package extension or separate bridge package.
   • Record the compatibility issue: SpinGlassPEPS currently requires Julia 1.11, while TenSolver currently supports Julia 1.10.
   • Record that SpinGlassPEPS brings CUDA/MKL/cuTENSOR/LowRankApprox/TSVD/TensorOperations-style dependencies and should not be loaded for ordinary TenSolver users.

4. Data model boundary

   • TenSolver public inputs are Boolean QUBO/PUBO and QUBODrivers/JuMP models.
   • SpinGlassPEPS expects Ising/Potts graph objects, cluster assignment rules, PEPS network geometry, contraction parameters, and branch-and-bound search parameters.
   • Integration needs explicit QUBO-to-Ising conversion and output decoding back to Boolean vectors.

5. Result model

   • TenSolver currently returns energy, Solution and QUBOTools SampleSet through the optimizer.
   • PEPS results should preserve ranked energies, states, probabilities, degeneracy, largest discarded probability, layout transformation, and droplet metadata where available.
   • The bridge should adapt PEPS solutions to TenSolver/QUBOTools results instead of leaking component internals by default.

6. Staged PR plan

   • PR 1: this design document.
   • PR 2: QUBO/Ising conversion utilities and tests.
   • PR 3: backend interface that preserves current DMRG default.
   • PR 4: optional SpinGlassPEPS bridge for direct structured inputs.
   • PR 5: QUBODrivers/JuMP attributes for selecting and configuring the PEPS backend.
   • PR 6: benchmark and documentation coverage.

7. Non-goals

   • Do not vendor SpinGlassPEPS internals into TenSolver.
   • Do not replace the existing minimize/maximize behavior.
   • Do not make GPU dependencies required for installing TenSolver.
   • Do not promise PEPS is best for arbitrary dense QUBOs.

8. Risks

   • Convention mistakes in Boolean-to-spin conversion.
   • Topology mismatch between QUBO variables and PEPS layouts.
   • Julia version compatibility.
   • GPU dependency footprint.
   • Approximate contraction instability at high inverse temperature.

Acceptance criteria

• A design document is added and included in the docs navigation if appropriate.
• The document states that SpinGlassPEPS is optional and structured-graph-specific.
• The document defines the stacked PR sequence and what each PR should contain.
• No new runtime dependencies are added.
• No public TenSolver solver behavior changes.

Out of scope

• Implementing conversions.
• Adding backend dispatch.
• Adding SpinGlassPEPS dependencies.
• Running SpinGlassPEPS benchmarks.

[bernalde]

Branch hygiene note for PR automation:

This issue is the root of the SpinGlassPEPS sequence. Keep the PR for this issue based on the repository default branch (main) after fetching and fast-forwarding origin/main.

Current PR: #41 (docs/issue-35-spinglasspeps-design -> main).

Later SpinGlassPEPS PRs must not permanently stack on this branch. After this PR lands, downstream issue branches should be rebased or recreated from current origin/main and their PR base should be 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: none for this root issue