refactor: consolidate polish helper, collapse duplicated app/bench/relaxation code, share test fixtures, bump 0.6.0

- qqa.polish.apply_polish_if_improves: single entry point for the
  greedy 1-flip QUBO polish so qqa.anneal / simulated_annealing /
  population_annealing and both PI-GNN trainers route through one
  helper instead of five near-identical guarded blocks.
- SpinRelaxation.perturb_ now inherits from BinaryRelaxation; both
  relaxations share the same [0,1] latent cube and noise schedule.
- qqa.bench: _load_bench_discs and _load_plot_benchmarks unified onto
  _load_scripts_module(name).
- sa._qubo_glauber_sweep deprecated alias dropped (only in-tree
  diagnostic caller updated).
- app/_common.retheme_plotly replaces the _retheme clone previously
  duplicated in 2_Visualize.py and 3_Compare.py.
- app/_common.as_numpy replaces the _as_np / _as_numpy clone shared
  with _solution_viz.py.
- tests/conftest.py introduced with APP, PAGE_DIR, make_problem_config
  and set_slider helpers; test_gui_apptest.py drops twelve inline
  problem_config dicts (-60 lines) and its local _set_slider.
- pyproject adds pythonpath = ["tests"] so the conftest helpers are
  importable from sibling test modules.
- CHANGELOG catch-up for 0.5.1 / 0.5.2 / 0.5.3 / 0.6.0.
- pyproject version 0.5.3 -> 0.6.0; uv.lock refreshed.

Net diff: 15 files changed, +242 / -207 lines.
Gates: ruff check + ruff format + pytest (371 passed) + mkdocs --strict
all green.

Made-with: Cursor

Author: Yuma Ichikawa

CHANGELOG.md

@@ -6,6 +6,108 @@ follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-04-20
+
+### Added
+
+- **`qqa.polish.apply_polish_if_improves`**: single entry point for the
+  greedy 1-flip QUBO polish post-processing. `qqa.anneal`,
+  `qqa.simulated_annealing`, `qqa.population_annealing` and both
+  PI-GNN trainers now route through this helper so every backend has
+  the same "monotone free improvement" contract without five copies of
+  the same `if polish and Q_mat is not None: …` block.
+- **Shared test fixtures** at `tests/conftest.py`: `APP`, `PAGE_DIR`
+  path constants, a `make_problem_config(kind, size, **extra)` factory
+  and a `set_slider` helper. Test modules now import these directly,
+  eliminating twelve copies of the same ``problem_config`` literal in
+  `test_gui_apptest.py`.
+- **`app/_common.retheme_plotly(fig)`**: replaces the ``_retheme`` clone
+  previously defined once per Streamlit page. Import it alongside
+  `plotly_layout` so every chart stays in step with the active theme.
+- **`app/_common.as_numpy(x)`** (public alias of the former `_as_np`):
+  imported by `_solution_viz.py` so the two modules share a single
+  tensor-to-numpy conversion path.
+
+### Changed
+
+- **Benchmark suite refreshed**: the project version now tracks the
+  "qqa4co-bench" HF dataset (coloring / mis-rrg / ea3d /
+  balanced-partition / MaxCut G-set families), wired through the
+  `qqa.bench` public API and `qqa bench run|plot|list|setup` CLI.
+- `SpinRelaxation.perturb_` now inherits from `BinaryRelaxation` —
+  both relaxations share the same latent cube `[0, 1]` and therefore
+  the same noise + ``clamp_`` schedule. Removes a silent copy-paste
+  drift risk.
+- `qqa.bench` collapsed `_load_bench_discs` and `_load_plot_benchmarks`
+  onto a shared `_load_scripts_module(name)` helper so the two
+  ``sys.path`` / ``importlib`` call sites no longer drift.
+- ``tests/`` directory is now on the pytest ``pythonpath`` so test
+  modules can ``from conftest import …`` the shared helpers.
+
+### Removed
+
+- **`qqa.sa._qubo_glauber_sweep` deprecated alias** dropped — it
+  forwarded to `_qubo_seq_glauber_sweep` and was only referenced by an
+  in-tree diagnostic script (updated). The buggy parallel-update
+  semantics it warned about have been gone since 0.4.0.
+
+## [0.5.3] - 2026-04-20
+
+### Added
+
+- **Backend-aware Visualize layout**: the Streamlit Visualize page now
+  shows PQQA-only tabs for PQQA runs (family tree, PCA embedding,
+  diversity, parallel coordinates) and PA-only tabs for PA runs
+  (ESS, free-energy trajectory, equilibration diagnostic,
+  Thermodynamics, Lineage vs energy, Ancestry Sankey). Empty
+  "No snapshots recorded" placeholders are gone.
+- **Up-front PA capability probe** in the Solve page: problems that
+  PA cannot sample (categorical / structured binary, e.g. TSP, QAP,
+  Coloring, NQueens) now trigger a clear warning banner and disable
+  the Run button, instead of surfacing a cryptic ``einsum`` /
+  ``NotImplementedError`` mid-run.
+- **Three PA-specific visualisation tabs**: Thermodynamics (Q vs β,
+  internal energy, specific heat), Lineage vs energy, Ancestry
+  Sankey.
+
+### Changed
+
+- `qqa.simulated_annealing` / `qqa.population_annealing` now accept
+  `polish=True/False` and expose a `polished_sol` field, matching the
+  contract `qqa.anneal` has always had. The 1-flip polish is default-on
+  across all backends so the "best_obj" score card reflects the same
+  post-processing everywhere.
+- `_validate_chain_problem` (used by both SA and PA) now rejects
+  structured `BinaryRelaxation` (non-flat `shape_fn`, e.g. TSP)
+  with an actionable error steering users to `qqa.anneal`.
+
+## [0.5.2] - 2026-04-20
+
+### Added
+
+- **`qqa.bench` public Python API** (`run`, `plot`, `list_suites`,
+  `resolve_suite`) mirroring the `qqa bench` CLI so notebooks can
+  dispatch a benchmark without subprocess boilerplate.
+- **Polished benchmark report figure** (`scripts/plot_benchmarks.py`)
+  and the corresponding `qqa bench plot` CLI flow.
+
+### Changed
+
+- HF Hub dataset renamed to `qqa4co-bench` (was `discs-benchmarks`);
+  `scripts/setup_discs_data.sh` and all docs follow suit.
+
+## [0.5.1] - 2026-04-19
+
+### Added
+
+- **`qqa.population_annealing`**: Population Annealing backend with
+  parallel chain sampling, importance resampling between inverse
+  temperatures, full free-energy / log-Z estimates and an optional
+  genealogy / ancestry record. `PAResult` dataclass and
+  `qqa solve --backend pa` CLI expose the new path.
+- **MaxCut G-set benchmark family** via
+  `scripts/fetch_gset_data.py` + `scripts/maxcut_gset_g70.py`.
+
 ## [0.5.0] - 2026-04-19
 
 ### Added

app/_common.py

@@ -294,6 +294,21 @@ def plotly_layout(theme: str | None = None, **overrides) -> dict:
     return base
 
 
+def retheme_plotly(fig):
+    """Reskin a Plotly figure so its palette matches the active theme.
+
+    Every page mirrors this pattern — wrap any ``viz`` figure in
+    ``retheme_plotly(...)`` before ``st.plotly_chart``. Errors from older
+    figure objects that don't expose ``update_layout`` are intentionally
+    swallowed so a single bad chart never breaks the whole page.
+    """
+    import contextlib  # noqa: PLC0415 - keep optional import local
+
+    with contextlib.suppress(Exception):
+        fig.update_layout(**plotly_layout())
+    return fig
+
+
 def apply_theme() -> None:
     """Inject the active theme's CSS, professional-academic in light mode."""
     theme = get_theme()
@@ -1955,12 +1970,24 @@ def _hopfield_preview(problem: Any) -> None:
     )
 
 
-def _as_np(x) -> np.ndarray:
+def as_numpy(x) -> np.ndarray:
+    """Return a CPU ``numpy`` view of a torch tensor / array / scalar.
+
+    Shared across the app (problem previews, solution viz). Lives here
+    rather than at each import site so behaviour stays consistent if we
+    ever need to e.g. detach non-leaf autograd graphs or handle BF16.
+    """
     if hasattr(x, "detach"):
         return x.detach().cpu().numpy()
     return np.asarray(x)
 
 
+# Backwards-compatible alias — callers inside ``_common.py`` still use
+# ``_as_np``. Keeping the alias avoids a large patch and preserves the
+# "private helper" reading for module-internal call sites.
+_as_np = as_numpy
+
+
 _DEDICATED_PREVIEWS: dict[str, callable] = {
     "tsp": _tsp_preview,
     "qap": _qap_preview,

app/_solution_viz.py

@@ -28,20 +28,14 @@
 import numpy as np
 import plotly.graph_objects as go
 import streamlit as st
+from _common import as_numpy as _as_numpy
 from _common import hex_to_rgba, palette, plotly_layout
 
 # ---------------------------------------------------------------------------
 # Helpers
 # ---------------------------------------------------------------------------
 
 
-def _as_numpy(x) -> np.ndarray:
-    """Return a CPU ``numpy`` view of a torch tensor / array / scalar."""
-    if hasattr(x, "detach"):
-        x = x.detach().cpu()
-    return np.asarray(x)
-
-
 def _graph_layout(g: nx.Graph, seed: int = 0) -> dict:
     """Cache-free 2-D layout suitable for the solution plots."""
     if g.number_of_nodes() <= 40:

app/pages/2_Visualize.py

@@ -22,6 +22,9 @@
     sidebar_brand,
     theme_toggle_in_sidebar,
 )
+from _common import (
+    retheme_plotly as _retheme,
+)
 from _solution_viz import render_solution_view  # noqa: E402
 
 from qqa import visualization as viz  # noqa: E402
@@ -205,13 +208,6 @@ def _tab_or_noop(key: str):
 tab_pa_sankey = _tab_or_noop("pa_sankey")
 
 
-def _retheme(fig):
-    """Reskin a Plotly figure produced by ``viz`` to the current theme."""
-    with contextlib.suppress(Exception):
-        fig.update_layout(**plotly_layout())
-    return fig
-
-
 with tab_hist:
     try:
         fig = viz.plot_history(result, backend="plotly", show=False)

app/pages/3_Compare.py

@@ -7,7 +7,6 @@
 
 from __future__ import annotations
 
-import contextlib
 import itertools
 import sys
 from pathlib import Path
@@ -23,18 +22,15 @@
     sidebar_brand,
     theme_toggle_in_sidebar,
 )
+from _common import (
+    retheme_plotly as _retheme,
+)
 
 import qqa  # noqa: E402
 from qqa import visualization as viz  # noqa: E402
 from qqa.relaxation import CategoricalRelaxation  # noqa: E402
 
 
-def _retheme(fig):
-    with contextlib.suppress(Exception):
-        fig.update_layout(**plotly_layout())
-    return fig
-
-
 def _scalar_best(obj) -> float:
     """Return a Python float regardless of whether ``best_obj`` is a list."""
     if hasattr(obj, "tolist"):

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "qqa"
-version = "0.5.3"
+version = "0.6.0"
 description = "Quasi-Quantum Annealing (QQA): a general-purpose GPU solver for combinatorial and spin-glass optimization, with PI-GNN/CPRA and a parallel SA baseline."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -144,6 +144,10 @@ dev = [
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+# Add tests/ to sys.path so test modules can ``from conftest import ...``
+# for the helpers exposed in tests/conftest.py (APP, PAGE_DIR,
+# make_problem_config, set_slider).
+pythonpath = ["tests"]
 addopts = "-ra"
 filterwarnings = [
     "ignore::DeprecationWarning:qqa.legacy",

src/qqa/annealing.py

@@ -20,7 +20,7 @@
 import torch
 
 from qqa.callbacks import Callback, CallbackState, HistoryRecorder
-from qqa.polish import greedy_one_flip
+from qqa.polish import apply_polish_if_improves
 from qqa.problems.base import COProblem
 from qqa.relaxation import _default_penalty_from_forward
 from qqa.schedule import LinearBGSchedule
@@ -380,17 +380,14 @@ def anneal(
     # contract is undefined). When the polish strictly improves the QUBO
     # objective, we hot-swap best_sol / best_obj / score so callers reading
     # ``result.best_sol`` automatically benefit.
-    polished_sol: torch.Tensor | None = None
-    if polish and not is_batch and getattr(problem, "Q_mat", None) is not None:
-        polished_sol = greedy_one_flip(problem, best_sol)
-        with torch.no_grad():
-            pol_obj = float(problem.loss_fn(polished_sol.unsqueeze(0)).item())
-        if pol_obj < best_obj:
-            best_sol = polished_sol
-            best_obj = pol_obj
-            score = safe_score_summary(problem, best_sol, fallback_obj=float(best_obj))
-            if verbose:
-                print(f"  POLISH    : 1-flip improved best_obj -> {best_obj}")
+    prev_obj = best_obj
+    best_sol, best_obj, polished_sol = apply_polish_if_improves(
+        problem, best_sol, best_obj, polish=polish and not is_batch
+    )
+    if polished_sol is not None and best_obj < prev_obj:
+        score = safe_score_summary(problem, best_sol, fallback_obj=float(best_obj))
+        if verbose:
+            print(f"  POLISH    : 1-flip improved best_obj -> {best_obj}")
 
     return AnnealResult(
         best_sol=best_sol,

src/qqa/bench.py

@@ -71,18 +71,25 @@ def _scripts_dir() -> Path:
     )
 
 
-def _load_bench_discs():
+def _load_scripts_module(name: str):
+    """Import a module from ``scripts/`` (``bench_discs`` / ``plot_benchmarks``).
+
+    Both runners live as plain ``.py`` files next to the repo and are *not*
+    shipped in the wheel, so we splice ``scripts/`` into ``sys.path`` once
+    per call and let :mod:`importlib` do the rest.
+    """
     sd = _scripts_dir()
     if str(sd) not in sys.path:
         sys.path.insert(0, str(sd))
-    return importlib.import_module("bench_discs")
+    return importlib.import_module(name)
+
+
+def _load_bench_discs():
+    return _load_scripts_module("bench_discs")
 
 
 def _load_plot_benchmarks():
-    sd = _scripts_dir()
-    if str(sd) not in sys.path:
-        sys.path.insert(0, str(sd))
-    return importlib.import_module("plot_benchmarks")
+    return _load_scripts_module("plot_benchmarks")
 
 
 # --------------------------------------------------------------------------- #

src/qqa/pa.py

@@ -41,7 +41,7 @@
 
 import torch
 
-from qqa.polish import greedy_one_flip
+from qqa.polish import apply_polish_if_improves
 from qqa.sa import (
     _build_beta_schedule,
     _qubo_seq_glauber_sweep,
@@ -422,18 +422,12 @@ def population_annealing(
     best_sol_disc = best_sol.detach()
 
     # Default-on greedy 1-flip polish. Shared with :func:`qqa.anneal` via
-    # ``qqa.polish.greedy_one_flip``; noop when ``Q_mat`` is absent (spin
-    # / categorical / batched problems). The polish strictly improves
-    # ``best_obj`` on QUBO landscapes where the MCMC stopped short of a
-    # 1-flip local minimum, so PA matches PQQA's post-processing contract.
-    polished_sol: torch.Tensor | None = None
-    if polish and getattr(problem, "Q_mat", None) is not None:
-        polished_sol = greedy_one_flip(problem, best_sol_disc)
-        with torch.no_grad():
-            pol_obj = float(problem.loss_fn(polished_sol.unsqueeze(0)).item())
-        if pol_obj < best_obj:
-            best_obj = pol_obj
-            best_sol_disc = polished_sol.detach()
+    # ``qqa.polish.apply_polish_if_improves``; noop when ``Q_mat`` is absent
+    # (spin / categorical / batched problems). PA therefore matches PQQA's
+    # post-processing contract by construction.
+    best_sol_disc, best_obj, polished_sol = apply_polish_if_improves(
+        problem, best_sol_disc, best_obj, polish=polish
+    )
 
     score = safe_score_summary(problem, best_sol_disc, fallback_obj=float(best_obj))