Add JuMP PEPS backend attributes

[bernalde]

Summary

• Adds raw optimizer attributes for backend selection and PEPS configuration in the QUBODrivers/JuMP optimizer.
• Keeps DMRG as the default and supports explicit :dmrg/"dmrg" selection.
• Requires explicit PEPS topology metadata, constructs PEPSBackend, adapts PEPSSolution states into QUBOTools samples, and attaches PEPS metadata to the returned SampleSet.
• Documents JuMP PEPS backend selection and updates the SpinGlassPEPS integration design notes.

Tests run

• julia +1.12 --project=. -e 'using Pkg; Pkg.test()' - passed. The optional SpinGlassPEPS extension solve is reported as a skipped/broken test when SpinGlass component packages are not installed.
• julia --project=docs/ docs/make.jl local - passed.
• git diff --check - passed.

Notes

• A direct include("test/jump.jl") run under the root package project is not a valid targeted command because JuMP is a test-only dependency in this repository; the JuMP coverage was run through Pkg.test().
• The live PEPS optimizer solve remains gated on the optional SpinGlass component packages.

Closes #39

[codecov]

Codecov Report

❌ Patch coverage is 83.33333% with 11 lines in your changes missing coverage. Please review.
✅ Project coverage is 73.44%. Comparing base (f3c4db1) to head (f72bb06).

Files with missing lines	Patch %	Lines
src/TenSolver.jl	83.33%	11 Missing ⚠️

Additional details and impacted files

@@                            Coverage Diff                             @@
##           feature/issue-38-spinglasspeps-backend      #45      +/-   ##
==========================================================================
+ Coverage                                   72.84%   73.44%   +0.60%     
==========================================================================
  Files                                           6        6              
  Lines                                         475      546      +71     
==========================================================================
+ Hits                                          346      401      +55     
- Misses                                        129      145      +16     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[bernalde]

GitHub rejected REQUEST_CHANGES because the authenticated account owns this pull request. The blocking comment below is blocking from a maintainer review perspective. I would not merge this until the blocking issue above is addressed.

Blocking issue found: the JuMP-facing PEPS backend selection is public, but the optional SpinGlass component stack still does not resolve with TenSolver and the actual PEPS optimizer success path is skipped in CI. I would not merge this until the blocking issue above is addressed.

Tests run locally:

• git diff --check origin/feature/issue-38-spinglasspeps-backend...HEAD
• julia --project=. -e "using Pkg; Pkg.instantiate()"
• julia --project=test -e "using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()"
• julia --project=test -e "using Test, Random, LinearAlgebra, TenSolver; include("test/utils.jl"); include("test/jump.jl")"
• julia --project=. -e "using Pkg; Pkg.test()"
• julia --project=docs/ -e "using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()"
• julia --project=docs/ docs/make.jl local
• julia --project=/tmp/tensolver-pr45-opt -e "using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.add(["SpinGlassNetworks", "SpinGlassEngine", "SpinGlassTensors"])" failed with the known Parsers/CSV/InlineStrings resolver conflict
• local fake-PEPS JuMP integration probe passed, showing the missing success-path test can be covered without optional packages

[bernalde]

Blocking: This exposes backend = :peps through the JuMP optimizer, but the optional SpinGlass component stack still cannot be installed together with TenSolver and CI skips the only real PEPS optimizer solve when those packages are absent. I reproduced the resolver failure in a fresh environment: adding SpinGlassNetworks, SpinGlassEngine, and SpinGlassTensors conflicts through SpinGlassNetworks -> CSV/Parsers and TenSolver/QUBOTools -> InlineStrings/Parsers. That leaves this new public attribute path without a runnable registered install path or CI coverage of the success branch. Please either keep the PEPS JuMP attributes and public docs internal until the optional stack resolves, or fix the dependency/compat strategy and add CI coverage. At minimum, add a fake-extension integration test that defines TenSolver._solve_ising(::PEPSBackend, ...) and drives JuMP.optimize! through this branch so the SampleSet and metadata path is covered without the optional packages.

[bernalde]

Addressed in f674a37: added a fake AbstractStructuredTopology JuMP test that drives backend = :peps through JuMP.optimize!, then checks objective/primal values plus QUBOTools solution metadata and reads in test/jump.jl. The optional real SpinGlass install path remains a follow-up once that dependency stack resolves.

[bernalde]

Nonblocking: This cycles retained PEPS states evenly and ignores psi.probabilities, while sample(::PEPSSolution) samples by those weights and num_reads is exposed as a sampling count. The resulting SampleSet read counts can misrepresent the PEPS distribution for downstream QUBOTools consumers. Consider generating samples with sample(psi) for num_reads, or converting probabilities into reads counts while preserving the full retained-state data under metadata[\"peps\"].

[bernalde]

Addressed in f674a37: _qubo_samples(::PEPSSolution, ...) now maps psi.probabilities to deterministic QUBOTools reads counts instead of cycling states. test/jump.jl covers the weighted read counts.

[bernalde]

Pushed commit:

• f674a37 Address PEPS JuMP review coverage (Add JuMP PEPS backend attributes #45)

Main changes:

• Added fake structured PEPS topology coverage that drives JuMP.optimize! through backend = :peps without requiring the optional SpinGlass packages.
• Asserted the resulting JuMP objective/primal values and the attached QUBOTools solution metadata/read counts.
• Changed PEPS SampleSet adaptation to convert retained-state probabilities into deterministic reads counts instead of cycling retained states evenly.
• Allowed internal AbstractStructuredTopology values to pass through peps_topology, so tests and future extension code can provide structured topology objects directly.
• Added QUBOTools as a direct test dependency because the new JuMP test inspects the attached solution.

Tests run:

• julia +1.12 --project=test -e 'push!(LOAD_PATH, pwd()); using Test, Random, LinearAlgebra, TenSolver; include("test/utils.jl"); include("test/jump.jl")' passed. JuMP interface: 2 pass. JuMP backend attributes: 39 pass, 1 broken optional SpinGlassPEPS test.
• julia +1.12 --project=test -e 'push!(LOAD_PATH, pwd()); using Test, Random, LinearAlgebra, TenSolver; include("test/peps_backend.jl")' passed. PEPS backend core: 34 pass. Optional SpinGlassPEPS extension: 1 broken because the optional packages are not installed.
• julia +1.12 --project=. -e 'using Pkg; Pkg.test()' passed.

Comments intentionally not addressed:

• None. The real SpinGlassPEPS package resolver/installability issue remains outside this PR; this PR now covers the public JuMP PEPS branch with a fake-extension integration test until that optional stack is resolvable in CI.

Remaining risks/follow-up:

• The real optional SpinGlassPEPS optimizer success path is still skipped when SpinGlassNetworks, SpinGlassEngine, and SpinGlassTensors are absent.
• I also rebased and force-with-lease pushed the dependent PR Add PEPS docs, examples, and benchmarks #46 branch, docs/issue-40-peps-examples-benchmarks, onto the updated Add JuMP PEPS backend attributes #45 head.

[bernalde]

Final focused review of f674a37: no blocking or nonblocking issues found.

GitHub would not let this account submit APPROVE because it owns the pull request: "Review Can not approve your own pull request".

The new fake PEPS JuMP integration test now exercises backend = :peps through JuMP.optimize!, validates objective/primal values, and checks QUBOTools metadata/read counts without requiring the unresolved optional SpinGlass package stack. The PEPS SampleSet adaptation now derives deterministic read counts from psi.probabilities instead of cycling states evenly.

Evidence inspected:

• Current PR head is f674a37.
• GitHub checks are green for Julia lts/1/pre across Ubuntu, Windows, and macOS.
• Documentation build and documenter/deploy are green.
• Local focused tests already run on this head: git diff --check f72bb06..f674a37, focused test/jump.jl on Julia 1.11.5 and Julia 1.12.6, and a targeted _peps_read_counts probe; all passed, with the expected broken optional SpinGlass solve.

Merge recommendation: merge-ready from this focused review pass. The real SpinGlassPEPS dependency resolver issue remains an external follow-up before relying on the real optional backend in CI.