Epic: Open issue and PR execution map

[bernalde]

Snapshot

Created from the open GitHub state on 2026-06-08.

• Open issues: 12
• Open PRs: 12
• All open PRs were non-draft, mergeStateStatus = CLEAN, and had green checks at the time of this snapshot.
• Treat that green status as stale after every merge to main; rebase or update the next PR and rerun CI before merging it.

This issue is the coordination map for the current repo state. The goal is to avoid duplicate fixes, keep stacked PRs moving in dependency order, and decide where the backend architecture should land before the larger optional-backend work is merged.

Executive sequence

Recommended high-level order:

1. Land the single-variable QUBO fix once, preferably through PR Solve single-variable QUBO inputs exactly instead of crashing #50.
2. Rebase PRs that duplicated the single-variable fix and remove their copies.
3. Land CI modernization through PR Modernize Julia CI action pins #51 after the duplicate solver code is removed, or consciously choose PR Modernize Julia CI action pins #51 as the canonical combined fix and close PR Solve single-variable QUBO inputs exactly instead of crashing #50 as superseded.
4. Merge independent main-targeted solver fixes/features one at a time: Document DMRG mindim default #34, Fix QUBO local-minimum polish #32, Add Q-matrix preprocessing permutation #33.
5. Implement and merge the QUBOTools/QUBODrivers compat update for issue Update QUBOTools and QUBODrivers compat for QUBOTools 0.12.1 #47.
6. Decide the optional GenericTensorNetworks backend PR Add optional GenericTensorNetworks backend #31 before merging the PEPS backend-interface PRs.
7. Merge the SpinGlassPEPS stack in exact stack order: Document SpinGlassPEPS integration architecture #41 -> Add QUBO/Ising conversion utilities #42 -> Introduce solver backend interface #43 -> Add optional SpinGlassPEPS backend #44 -> Add JuMP PEPS backend attributes #45 -> Add PEPS docs, examples, and benchmarks #46.

The most important coordination point is the overlap between PR #50 and PR #51. Issue #49 says the one-variable crash should be fixed once, on its own. Issue #48 says CI modernization should not add package code. PR #51 is currently green because it includes a one-variable solver fix as a CI unblocker, but the cleaner long-term history is:

1. Merge Solve single-variable QUBO inputs exactly instead of crashing #50 as the canonical one-variable QUBO fix.
2. Rebase Modernize Julia CI action pins #51 onto updated main.
3. Remove the duplicated solver/test changes from Modernize Julia CI action pins #51 so it is CI-only.
4. Merge Modernize Julia CI action pins #51 for issue Modernize Julia CI cache action and workflow pins #48.

Alternative fast path:

• Merge Modernize Julia CI action pins #51 as-is, verify it fully resolves minimize/maximize crash on single-variable (1x1) QUBO inputs #49, then close Solve single-variable QUBO inputs exactly instead of crashing #50 as superseded.
• This is less clean because the issue Modernize Julia CI cache action and workflow pins #48 PR would include package code, but it is already green and may be acceptable if maintainers prefer fewer PR edits.

Do not merge both #50 and #51 as-is without a rebase/diff audit.

Open issue map

Issue	Area	Current PR	Recommended disposition
#49 minimize/maximize crash on single-variable (1x1) QUBO inputs	Correctness bug	#50, also duplicated in #51 and reported across older PRs	Make #50 the canonical fix if possible. Rebase/remove duplicate one-site code from #51, #34, #33, #41, and any other PR that carries it.
#48 Modernize Julia CI cache action and workflow pins	CI maintenance	#51	Merge after #50, with package-code overlap removed. If #51 remains combined, close #50 as superseded after verification.
#47 Update QUBOTools and QUBODrivers compat for QUBOTools 0.12.1	Dependency compatibility	No PR yet	Implement after base stabilization and before QUBODrivers-heavy backend PRs. Validate QUBOTools 0.12.1 and likely QUBODrivers 0.5 in a clean environment.
#40 [SpinGlassPEPS 6/6] Add PEPS backend docs, examples, and benchmark scripts	PEPS docs/examples/benchmarks	#46	Merge last in the PEPS stack, after #45.
#39 [SpinGlassPEPS 5/6] Expose PEPS backend through QUBODrivers and JuMP attributes	PEPS JuMP/QUBODrivers exposure	#45	Merge after #44 and after issue #47 is resolved or explicitly deemed not blocking.
#38 [SpinGlassPEPS 4/6] Add optional SpinGlassPEPS-backed structured solver path	Optional PEPS backend	#44	Merge after #43. Keep SpinGlass components optional and PEPS tests gated where dependencies are unavailable.
#37 [SpinGlassPEPS 3/6] Introduce solver backend interface while keeping DMRG default	Backend interface	#43	Merge after #42, but first resolve the relationship with #31 if #31 is intended to land.
#36 [SpinGlassPEPS 2/6] Add QUBO/Ising conversion utilities with exact tests	Conversion utilities	#42	Merge after #41. This is the correctness base for PEPS.
#35 [SpinGlassPEPS 1/6] Document integration architecture and backend boundary	Design docs	#41	Merge as the PEPS stack base after removing any duplicate one-variable fix if #50 lands first.
#19 Getting stuck on local minima	Solver quality/correctness	#32	Merge after the single-variable fix and CI modernization. Rebase before merge because src/solver.jl is high-conflict.
#12 Preprocessing: Implement Q-matrix permutation	Solver preprocessing enhancement	#33	Merge after core bug fixes. Rebase after #32 if #32 lands first because both affect solver behavior and samples.
#1 LAPACKException on some QUBO examples	Solver stability bug	#34	Merge early after #50/#51 because this is a user-facing bug fix. Remove duplicated one-variable code after #50.

Open PR map

PR	Base branch	Head branch	Linked issue	Status at snapshot	Merge notes
#51 Modernize Julia CI action pins	main	fix/issue-48-modernize-ci-actions	#48	Green, clean	Updates checkout/setup/cache/codecov majors. Also contains the one-variable solver fix. Prefer rebasing after #50 and making it CI-only.
#50 Solve single-variable QUBO inputs exactly instead of crashing	main	fix/issue-49-single-variable-solve	#49	Green, clean	Best canonical PR for #49. Merge first to de-duplicate the edge-case fix.
#46 Add PEPS docs, examples, and benchmarks	feature/issue-39-jump-peps-attrs	docs/issue-40-peps-examples-benchmarks	#40	Green, clean	Stack 6/6. Merge only after #45.
#45 Add JuMP PEPS backend attributes	feature/issue-38-spinglasspeps-backend	feature/issue-39-jump-peps-attrs	#39	Green, clean	Stack 5/6. Depends on #44 and may need adjustment after #47.
#44 Add optional SpinGlassPEPS backend	feature/issue-37-backend-interface	feature/issue-38-spinglasspeps-backend	#38	Green, clean	Stack 4/6. Optional component packages remain gated/unavailable in normal CI.
#43 Introduce solver backend interface	feature/issue-36-qubo-ising-conversion	feature/issue-37-backend-interface	#37	Green, clean	Stack 3/6. Potential conflict with #31, which also introduces backend abstractions.
#42 Add QUBO/Ising conversion utilities	docs/issue-35-spinglasspeps-design	feature/issue-36-qubo-ising-conversion	#36	Green, clean	Stack 2/6. Merge after #41.
#41 Document SpinGlassPEPS integration architecture	main	docs/issue-35-spinglasspeps-design	#35	Green, clean	Stack 1/6. Contains duplicate single-variable fix according to the PR body; remove that if #50 lands first.
#34 Fix QUBO DMRG LAPACK stability	main	fix/issue-1-lapack-qubo	#1	Green, clean	Bug fix. Rebase after #50/#51 and remove duplicate one-site path if present.
#33 Add Q-matrix preprocessing permutation	main	fix/issue-12-q-matrix-permutation	#12	Green, clean	Feature. Rebase after solver bug fixes and verify sample unpermutation still composes with polish/backend changes.
#32 Fix QUBO local-minimum polish	main	fix/issue-19-local-minima	#19	Green, clean	Bug/quality fix. Merge before preprocessing if maintainers prioritize correctness regression first.
#31 Add optional GenericTensorNetworks backend	main	codex/gtn-backend-integration	No open issue linked in body	Green, clean	Large optional-backend feature. Decide before #43; otherwise #43 and #31 may create competing backend abstractions.

Detailed merge plan

Phase 0: pre-merge discipline

Before each merge:

• Update the PR branch from the latest main.
• Rerun GitHub CI after the update.
• Inspect the diff for duplicated one-variable solver code.
• Avoid batching merges. Merge one PR, wait for main to settle, then update the next PR.

Expected local verification commands, as applicable:

julia --project=. -e 'using Pkg; Pkg.test()'
julia --project=docs/ docs/make.jl local
git diff --check

For CI-only changes, additionally verify the GitHub matrix, cache restore/save, and Codecov upload behavior.

Phase 1: de-duplicate the one-variable QUBO fix

Primary path:

1. Merge Solve single-variable QUBO inputs exactly instead of crashing #50.
2. Confirm minimize/maximize crash on single-variable (1x1) QUBO inputs #49 can be closed by Solve single-variable QUBO inputs exactly instead of crashing #50.
3. Rebase Modernize Julia CI action pins #51 onto main and remove solver/test changes already landed by Solve single-variable QUBO inputs exactly instead of crashing #50.
4. Rebase Document DMRG mindim default #34, Add Q-matrix preprocessing permutation #33, Document SpinGlassPEPS integration architecture #41, and any other affected PRs onto main; remove duplicated one-site special cases.
5. Re-run CI on each rebased PR.

Why this comes first:

• The one-variable crash is a small correctness bug and blocks clean CI in newer QUBODrivers coverage.
• Several PRs contain slightly different fixes. Landing it once reduces merge conflicts and review noise.

Fallback path:

1. Merge Modernize Julia CI action pins #51 as-is.
2. Verify minimize/maximize crash on single-variable (1x1) QUBO inputs #49 is fully covered by Modernize Julia CI action pins #51's tests and behavior.
3. Close Solve single-variable QUBO inputs exactly instead of crashing #50 as superseded, or rework it into an extra-test-only PR if it has coverage worth keeping.
4. Rebase older PRs and remove their duplicate one-site fixes.

Phase 2: CI modernization

Target: #51 for #48.

Acceptance gate:

• Existing OS/version/arch matrix remains unchanged unless a separate issue is opened.
• actions/checkout, julia-actions/setup-julia, julia-actions/cache, and codecov/codecov-action are updated as intended.
• julia-actions/cache@v3 restores/saves successfully.
• codecov/codecov-action@v6 uploads successfully or is split into a separate follow-up if token/configuration changes are required.

Preferred merge point:

• After Solve single-variable QUBO inputs exactly instead of crashing #50 if Solve single-variable QUBO inputs exactly instead of crashing #50 is the canonical one-variable fix.
• Before the remaining solver and backend PRs, so future branches validate against the modernized workflow.

Phase 3: main-line solver fixes and enhancements

Recommended order:

1. Document DMRG mindim default #34 for LAPACKException on some QUBO examples #1: DMRG/LAPACK stability and VRP regression.
2. Fix QUBO local-minimum polish #32 for Getting stuck on local minima #19: local-minimum polish and regression objective.
3. Add Q-matrix preprocessing permutation #33 for Preprocessing: Implement Q-matrix permutation #12: Q-matrix preprocessing permutation.

Rationale:

• Document DMRG mindim default #34 is a stability bug.
• Fix QUBO local-minimum polish #32 is a solver-quality/correctness regression reported by a user.
• Add Q-matrix preprocessing permutation #33 is a preprocessing enhancement that should be rebased after the core solver behavior is settled.

Conflict notes:

• Document DMRG mindim default #34, Fix QUBO local-minimum polish #32, and Add Q-matrix preprocessing permutation #33 all touch solver behavior. Expect src/solver.jl and QUBO tests to need rebases.
• If Add Q-matrix preprocessing permutation #33 lands after Fix QUBO local-minimum polish #32, explicitly verify that preprocessing preserves caller-facing variable order and that polish still evaluates samples in the correct order.
• If Add Q-matrix preprocessing permutation #33 lands before Fix QUBO local-minimum polish #32, verify Fix QUBO local-minimum polish #32's branch-and-bound polish sees the intended original/permuted variable convention.

Phase 4: dependency compatibility

Target: issue #47. No PR is open yet.

Do this after the base solver fixes and before QUBODrivers-heavy optional backend work.

Required work:

• Audit current TenSolver behavior against QUBOTools 0.12.1.
• Audit QUBODrivers integration against the latest compatible line, likely 0.5 if the optimizer interface still matches.
• Widen [compat] only as far as validated.
• Run normal tests and explicit JuMP/QUBODrivers integration tests in a clean environment.
• Prepare release notes for a TenSolver release if the compat update is safe.

Why this comes before #45:

• Add JuMP PEPS backend attributes #45 exposes PEPS through QUBODrivers/JuMP attributes.
• If QUBODrivers APIs changed between the current bound and 0.5, Add JuMP PEPS backend attributes #45 should be written against the new supported interface rather than merged and immediately reworked.

Also consider #31 here:

• Add optional GenericTensorNetworks backend #31 exposes backend attributes through QUBODrivers too.
• If Add optional GenericTensorNetworks backend #31 is going to merge, it should also be validated against the compat target from Update QUBOTools and QUBODrivers compat for QUBOTools 0.12.1 #47.

Phase 5: optional GenericTensorNetworks decision

Target: #31.

#31 is green and clean, but it is large and not mapped to an open issue in the current issue list. It introduces:

• Internal pseudo-Boolean objective representation.
• DMRGBackend and optional GTNBackend dispatch.
• A Julia package extension for GenericTensorNetworks.
• QUBODrivers backend attributes.
• Tests and docs/examples.

Decision needed before PEPS PR #43:

• If Add optional GenericTensorNetworks backend #31 is accepted, merge it before Introduce solver backend interface #43 and rework Introduce solver backend interface #43 to extend the backend abstraction already introduced by Add optional GenericTensorNetworks backend #31.
• If Add optional GenericTensorNetworks backend #31 is deferred, explicitly keep the PEPS stack as the current backend-interface path and require Add optional GenericTensorNetworks backend #31 to rebase on the final PEPS-aware backend API later.
• If Add optional GenericTensorNetworks backend #31 is too broad, split it into an issue-backed stack before merging.

Do not let #31 and #43 independently establish incompatible backend APIs.

Phase 6: SpinGlassPEPS stack

Merge the stack exactly in dependency order:

1. Document SpinGlassPEPS integration architecture #41 closes [SpinGlassPEPS 1/6] Document integration architecture and backend boundary #35: design and architecture document.
2. Add QUBO/Ising conversion utilities #42 closes [SpinGlassPEPS 2/6] Add QUBO/Ising conversion utilities with exact tests #36: QUBO/Ising conversion utilities and exhaustive exact tests.
3. Introduce solver backend interface #43 closes [SpinGlassPEPS 3/6] Introduce solver backend interface while keeping DMRG default #37: backend interface while keeping DMRG default.
4. Add optional SpinGlassPEPS backend #44 closes [SpinGlassPEPS 4/6] Add optional SpinGlassPEPS-backed structured solver path #38: optional SpinGlassPEPS-backed structured direct API.
5. Add JuMP PEPS backend attributes #45 closes [SpinGlassPEPS 5/6] Expose PEPS backend through QUBODrivers and JuMP attributes #39: QUBODrivers/JuMP attributes for selecting PEPS.
6. Add PEPS docs, examples, and benchmarks #46 closes [SpinGlassPEPS 6/6] Add PEPS backend docs, examples, and benchmark scripts #40: PEPS docs, examples, and benchmark scripts.

Stack handling:

• After Document SpinGlassPEPS integration architecture #41 merges, retarget or rebase Add QUBO/Ising conversion utilities #42 onto main and rerun CI.
• Repeat that process for every next PR.
• Do not merge Add QUBO/Ising conversion utilities #42-Add PEPS docs, examples, and benchmarks #46 against stale intermediate bases without refreshing.
• If Add optional GenericTensorNetworks backend #31 lands first, Introduce solver backend interface #43 and later PRs must be reviewed for backend API alignment.
• If Update QUBOTools and QUBODrivers compat for QUBOTools 0.12.1 #47 lands first and changes QUBODrivers compatibility or APIs, Add JuMP PEPS backend attributes #45 must be reviewed specifically.

PEPS-specific validation gates:

• Conversion tests in Add QUBO/Ising conversion utilities #42 must prove objective equality and argmin preservation for TenSolver's Boolean convention.
• Backend interface in Introduce solver backend interface #43 must keep minimize, maximize, and QUBODrivers default behavior on DMRG.
• Optional PEPS code in Add optional SpinGlassPEPS backend #44 must not make SpinGlass component packages mandatory dependencies.
• QUBODrivers/JuMP PEPS exposure in Add JuMP PEPS backend attributes #45 must fail clearly when topology metadata is missing.
• Docs/benchmarks in Add PEPS docs, examples, and benchmarks #46 must not make long PEPS benchmarks part of normal CI.

Risk and conflict map

Duplicate one-variable QUBO fixes

Known overlap:

• Solve single-variable QUBO inputs exactly instead of crashing #50 is the focused fix for minimize/maximize crash on single-variable (1x1) QUBO inputs #49.
• Modernize Julia CI action pins #51 includes a one-variable fix as a CI unblocker.
• Document SpinGlassPEPS integration architecture #41 explicitly mentions the same fix.
• Document DMRG mindim default #34 and Add Q-matrix preprocessing permutation #33 mention one-variable paths.
• minimize/maximize crash on single-variable (1x1) QUBO inputs #49 notes duplicated ad hoc fixes across Fix QUBO local-minimum polish #32, Add Q-matrix preprocessing permutation #33, Document DMRG mindim default #34, and Document SpinGlassPEPS integration architecture #41.

Resolution:

• Choose one canonical fix.
• Rebase every other PR and drop its copy.
• Keep or move only genuinely additional tests.

Solver-path conflicts

Likely affected PRs:

• Solve single-variable QUBO inputs exactly instead of crashing #50, Document DMRG mindim default #34, Fix QUBO local-minimum polish #32, Add Q-matrix preprocessing permutation #33, Add optional GenericTensorNetworks backend #31, Introduce solver backend interface #43.

Resolution:

• Merge from smallest correctness fix to broader feature.
• Re-run full QUBO, QUBODrivers, and docs tests after rebases.
• Pay attention to sample order, objective evaluation, and Solution membership behavior.

Backend abstraction conflicts

Likely affected PRs:

• Add optional GenericTensorNetworks backend #31 and Introduce solver backend interface #43.

Resolution:

• Decide Add optional GenericTensorNetworks backend #31 before Introduce solver backend interface #43.
• Maintain one backend abstraction that can support DMRG, GTN, and PEPS without parallel concepts.

QUBODrivers compatibility risk

Likely affected work:

• Update QUBOTools and QUBODrivers compat for QUBOTools 0.12.1 #47, Add optional GenericTensorNetworks backend #31, Add JuMP PEPS backend attributes #45, and existing JuMP/QUBODrivers tests.

Resolution:

• Resolve Update QUBOTools and QUBODrivers compat for QUBOTools 0.12.1 #47 before merging QUBODrivers-heavy backend features.
• Validate in clean environments rather than relying on ignored local manifests.

Optional dependency risk

Likely affected PRs:

• Add optional GenericTensorNetworks backend #31 and Add optional SpinGlassPEPS backend #44-Add PEPS docs, examples, and benchmarks #46.

Resolution:

• Keep optional packages out of mandatory [deps].
• Use package extensions or bridge packages.
• Gate tests that require heavy optional stacks.
• Ensure ordinary TenSolver install/test paths remain lightweight.

Definition of done for this epic

This epic can be closed when:

• Every open issue listed above is closed, intentionally superseded, or re-scoped into a newer issue.
• Every open PR listed above is merged, closed as superseded, or split into smaller tracked PRs.
• The one-variable QUBO fix exists in exactly one canonical mainline implementation.
• CI workflow pins are modernized and the matrix is green.
• QUBOTools/QUBODrivers compat is updated or explicitly blocked with a documented reason.
• The backend architecture decision between Add optional GenericTensorNetworks backend #31 and the PEPS stack is resolved.
• The SpinGlassPEPS stack is either merged through Add PEPS docs, examples, and benchmarks #46 or intentionally paused with the next blocking action documented.

[bernalde]

Status update after the TenSolver v0.2.0 release wave: #47 and #53 are now complete/superseded by the registered v0.2.0 release. Current open PR CI is green across the GitHub Actions rollups. The remaining actionable work in this repo is merge sequencing plus any maintainer resolution of review threads that are already addressed in commits but still unresolved in the GitHub UI. The stacked SpinGlassPEPS PRs should still be merged in order (#41 -> #42 -> #43 -> #44 -> #45 -> #46), with dependent branches rebased or retargeted after each merge.