Introduce solver backend interface

[bernalde]

Summary

• Adds AbstractTenSolverBackend and DMRGBackend as the core backend boundary.
• Routes public minimize calls through backend-specific dispatch while keeping the current DMRG implementation as the default.
• Allows explicit DMRG selection through backend = :dmrg or backend = DMRGBackend().
• Preserves maximize, QUBO/PUBO lowering, existing DMRG keywords, Solution, sampling, and QUBODrivers default behavior.
• Adds clear unavailable-backend errors for requests such as backend = :peps.
• Documents the backend boundary in the API docs and updates the SpinGlassPEPS design note.

This is stacked on PR #42 and targets feature/issue-36-qubo-ising-conversion.

Tests run

• git diff --check - passed.
• julia +1.12 --project=. -e 'using Test, Random, LinearAlgebra, TenSolver; include("test/backend.jl")' - passed, 13 tests.
• julia --project=docs/ docs/make.jl local - passed, including Documenter doctests.
• julia +1.12 --project=. -e 'using Pkg; Pkg.test()' - passed.

Notes

• No SpinGlassPEPS dependency is introduced.
• QUBODrivers/JuMP backend attributes remain out of scope for this PR and are planned for issue [SpinGlassPEPS 5/6] Expose PEPS backend through QUBODrivers and JuMP attributes #39.

Closes #37

[bernalde]

GitHub rejected REQUEST_CHANGES because this authenticated account is the pull request author, so I am submitting this as COMMENT. Maintainer recommendation: do not merge as-is.

Review summary:

1. Blocking issues: 1. The symbolic backend normalization is not extensible for the later optional backend = :peps path described by the docs.
2. Nonblocking issues: none.
3. Questions: none.
4. Tests run and outcomes:
   • julia --project=. -e 'using Pkg; Pkg.instantiate()': passed.
   • Targeted test/backend.jl on Julia 1.11.5: passed, 13/13.
   • Custom backend object dispatch probe: passed.
   • Symbol-extension dispatch probe: confirmed value-specific symbol extension is not reachable.
   • git diff --check origin/feature/issue-36-qubo-ising-conversion...HEAD: passed.
   • Targeted test/backend.jl on Julia 1.10.11: passed, 13/13.
   • julia --project=. -e 'using Pkg; Pkg.test()': passed.
   • Documented docs setup command: passed.
   • julia --project=docs/ docs/make.jl local: passed.
   • GitHub CI checks inspected: all current checks are passing.
5. Merge as-is: no.

I would not merge this until the blocking issue above is addressed.

[bernalde]

Blocking: This catches every Symbol backend in one concrete method, so an optional package extension cannot later implement the documented backend = :peps path with normal Julia dispatch. minimize(...; backend = :peps) will always enter this method and throw before backend-specific _minimize methods can run, which makes the new backend interface much harder to extend without editing core TenSolver again or overwriting this method.

Use a value-dispatch hook instead, for example _normalize_backend(backend::Symbol) = _normalize_backend(Val(backend)), _normalize_backend(::Val{:dmrg}) = default_backend, and a fallback _normalize_backend(::Val{backend}) where backend = throw(_backend_error(backend)). Then a PEPS extension can add _normalize_backend(::Val{:peps}) = PEPSBackend(...). Please also add a regression test with a fake symbolic backend so this extension path stays covered.

[bernalde]

Addressed in f4a3769. Symbol normalization now dispatches through Val(backend), :dmrg stays mapped to the default backend, and test/backend.jl covers a fake symbol-specific backend reaching its _minimize method.

[bernalde]

Pushed commit f4a37690dc4aa951bb013c978d0d983e8321118d.

Main changes:

• Changed symbolic backend normalization to use Val dispatch: _normalize_backend(backend::Symbol) = _normalize_backend(Val(backend)).
• Kept :dmrg mapped to the default backend and kept unloaded symbols like :peps on the existing clear error path.
• Added a regression test with a fake symbolic backend to prove an extension can register a symbol-specific normalization method and reach its backend-specific _minimize method.

Tests run:

• julia +1.12 --project=. -e 'using Test, Random, LinearAlgebra, TenSolver; include("test/backend.jl")' - passed, 19 tests.
• julia +1.12 --project=. -e 'using Pkg; Pkg.test()' - passed.
• julia --project=docs/ docs/make.jl local - passed.
• git diff --check - passed.

Comments intentionally not addressed: none.

Remaining risks/follow-up:

• The extension hook is still an internal TenSolver method, but it now supports the planned package-extension path without another core edit.

[bernalde]

Blocking: The PR introduces the backend boundary, but the committed symbol normalization currently hard-codes :dmrg and throws for every other symbol. That means a future optional extension cannot make backend = :peps work by adding a more specific method; core TenSolver would need another edit, which undercuts the extension path requested by issue #37 and described in the docs.

A concrete fix is to route symbols through Val, define the DMRG case in core, and leave the fallback on Val{backend} so extensions can add their own symbol mapping:

_normalize_backend(backend::Symbol) = _normalize_backend(Val(backend))
_normalize_backend(::Val{:dmrg}) = default_backend
function _normalize_backend(::Val{backend}) where {backend}
  throw(_backend_error(backend))
end

Then a later PEPS bridge can implement TenSolver._normalize_backend(::Val{:peps}) without modifying core. Please add a small regression test with a dummy symbol backend so this extension point stays protected.

[bernalde]

GitHub rejected APPROVE because this authenticated account is the pull request author, so I am submitting this as COMMENT. Maintainer recommendation: merge-ready as-is.

Review summary:

1. Blocking issues: none.
2. Nonblocking issues: none.
3. Questions: none.
4. Tests run and outcomes:
   • julia --project=. -e 'using Pkg; Pkg.instantiate()': passed.
   • Targeted test/backend.jl on Julia 1.11.5: passed, 19/19.
   • Targeted test/backend.jl on Julia 1.10.11: passed, 19/19.
   • Module-scoped fake backend extension probe: passed.
   • git diff --check origin/feature/issue-36-qubo-ising-conversion...HEAD: passed.
   • julia --project=. -e 'using Pkg; Pkg.test()': passed.
   • Documented docs setup command: passed.
   • julia --project=docs/ docs/make.jl local: passed.
   • GitHub CI checks inspected: all current checks are passing.
5. Merge as-is: yes.

The latest head uses Val dispatch for symbolic backend normalization and covers the extension path with a fake symbolic backend test. I found no actionable issues requiring inline comments.