Document SpinGlassPEPS integration architecture

[bernalde]

Summary

• Adds a SpinGlassPEPS integration architecture page to the generated docs.
• Records the planned optional structured-graph PEPS backend boundary, dependency policy, data/result model adapters, backend selection shape, staged PR plan, non-goals, and risks.
• Links the new page from the Documenter navigation and updates the docs guide page list.
• Fixes the existing one-variable solver edge case that made the QUBODrivers fixed-variable contract fail in CI by using an exact one-variable path instead of calling DMRG, which ITensorMPS does not support for system size 1.

Tests run

• julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()' - passed.
• julia --project=docs/ docs/make.jl local - passed, including Documenter doctests.
• julia +1.12 --project=. -e 'using Pkg; Pkg.test()' - passed.
• julia +1.12 --project=. -e 'using Test, Random, LinearAlgebra, TenSolver; include("test/utils.jl"); include("test/qubo.jl")' - passed, 82 tests.
• julia +1.10 --startup-file=no -e 'using Pkg; Pkg.activate(; temp=true); Pkg.develop(PackageSpec(path=pwd())); Pkg.add(["Aqua", "JuMP", "QUBODrivers"]); using Test, TenSolver; include("test/external.jl")' - passed, including QUBODrivers and Aqua.

Notes

• julia --project=. -e 'using Pkg; Pkg.test()' with the default local Julia 1.11.5 did not reach test execution because the local ignored root manifest was resolved with Julia 1.12.6 and Pkg could not locate OpenSSL_jll for the older active Julia. The LTS-relevant external test was therefore run in a fresh Julia 1.10 temporary environment.

Closes #35

[bernalde]

Blocking issues: none found in the changed documentation.

Nonblocking issues: none found.

Questions: none.

Tests run and outcomes:

• julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()' passed.
• julia --project=docs/ docs/make.jl local passed, including doctests and cross-reference checks.
• julia +1.12 --project=. -e 'using Pkg; Pkg.test()' passed.
• julia +1.10 --project=. -e 'using Pkg; Pkg.test()' did not reach test execution locally because the root manifest was resolved with Julia 1.12.6 and Pkg could not locate OpenSSL_jll under Julia 1.10.11.
• The PR CI LTS Ubuntu job is failing in the existing QUBODrivers fixed-variable suite when TenSolver.Optimizer is exercised on a one-variable model; ITensorMPS.dmrg errors that system size 1 is unsupported. The documentation job passed.

Merge as-is: not while the required test workflow is red. I did not find a PR-diff issue that needs an inline comment, but this should get a green test run or an explicit maintainer decision on the unrelated LTS failure before merge.

[bernalde]

Reviewed the PR feedback.

Commits pushed:

• None. There were no actionable comments on the changed documentation.

Main changes made:

• No file changes. The only review comment reports no blocking or nonblocking issues in the docs diff.

Tests run:

• No new local tests were run because no code or documentation changes were made in response to the review.
• Existing validation from the PR remains: docs build and Documenter doctests passed locally, and julia +1.12 --project=. -e 'using Pkg; Pkg.test()' passed locally.
• Current PR checks: documentation build passed; documenter/deploy passed; the test workflow is red after Julia lts - ubuntu-latest - x64 failed and the remaining matrix jobs were cancelled by fail-fast.

Comments intentionally not addressed:

• The review's CI note is not being fixed in this docs-only PR. The failure is in the existing QUBODrivers fixed-variable contract path for a one-variable model, where ITensorMPS.dmrg errors because system size 1 is unsupported. Fixing that requires a solver/optimizer behavior change outside the scope of issue [SpinGlassPEPS 1/6] Document integration architecture and backend boundary #35 and this documentation-only PR.

Remaining risks or follow-up:

• This PR remains blocked if the required test workflow must be green before merge. The follow-up should be a separate code PR for the one-variable/fixed-variable optimizer edge case, or an explicit maintainer decision to merge this docs-only PR despite the unrelated red test workflow.

[bernalde]

Pushed the requested CI fix.

Commits pushed:

• 753ff05 - Fix one-variable solver edge case (#35)

Main changes made:

• Added an exact one-variable path in src/solver.jl so system-size-1 QUBO/PUBO/optimizer reductions do not call DMRG.
• Added regression coverage in test/qubo.jl for one-variable minimization, linear+constant terms, degeneracy, and maximization.

Tests run:

• julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()' passed.
• julia --project=docs/ docs/make.jl local passed.
• julia +1.12 --project=. -e 'using Test, Random, LinearAlgebra, TenSolver; include("test/utils.jl"); include("test/qubo.jl")' passed, 82 tests.
• julia +1.12 --project=. -e 'using Pkg; Pkg.test()' passed.
• julia +1.10 --startup-file=no -e 'using Pkg; Pkg.activate(; temp=true); Pkg.develop(PackageSpec(path=pwd())); Pkg.add(["Aqua", "JuMP", "QUBODrivers"]); using Test, TenSolver; include("test/external.jl")' passed: QUBODrivers 130/130 and Aqua 11/11.
• PR CI rerun is green across the test matrix and docs.

Comments intentionally not addressed:

• None remaining. There were no inline review comments.

Remaining risks:

• The one-variable path returns one exact stats entry rather than a DMRG sweep history, which is intentional because no DMRG run exists for system size 1.

[bernalde]

GitHub rejected an APPROVE review from this authenticated account because it is the PR author, so this is submitted as a COMMENT review. The maintainer recommendation is still merge-ready as-is.

1. Blocking issues: none.
2. Nonblocking issues: none.
3. Questions: none.
4. Tests run and outcomes:
   • git diff --check origin/main...HEAD: passed.
   • julia +1.12 --project=. -e 'using Test, Random, LinearAlgebra, TenSolver; include("test/utils.jl"); include("test/qubo.jl")': passed, 82 tests.
   • julia --project=docs/ docs/make.jl local: passed.
   • julia +1.12 --project=. -e 'using Pkg; Pkg.test()': passed.
   • gh pr checks 41 --watch --fail-fast: all PR checks passed across Julia 1, LTS, prerelease, docs build, and Documenter deploy.
5. Merge recommendation: merge-ready as-is.

[bernalde]

GitHub rejected an APPROVE review from this authenticated account because it is the PR author, so this is submitted as a COMMENT review. The maintainer recommendation is still merge-ready as-is.

Blocking issues: none.

Nonblocking issues: none.

Questions: none.

Tests run and outcomes:

• git diff --check origin/main...HEAD: passed.
• julia --project=. -e 'using Test, Random, LinearAlgebra, TenSolver; include("test/utils.jl"); include("test/qubo.jl")': passed, 82 tests.
• julia --project=. -e 'using Pkg; Pkg.test()': passed on Julia 1.11.5.
• julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()': passed.
• julia --project=docs/ docs/make.jl local: passed.
• julia +1.10 --startup-file=no -e 'using Pkg; Pkg.activate(; temp=true); Pkg.develop(PackageSpec(path=pwd())); Pkg.add(["Aqua", "JuMP", "QUBODrivers"]); using Test, Random, LinearAlgebra, TenSolver; include("test/utils.jl"); include("test/qubo.jl"); include("test/external.jl")': passed; QUBO 82/82, QUBODrivers 129/129, Aqua 11/11.
• One-variable smoke checks for integer QUBO input and single-variable DynamicPolynomials input: passed.

Merge as-is: yes. I found no actionable correctness, API, documentation, or maintainability issues in this PR.