feat(ui): polish + warm-start toggles, expose new problem catalog

Solve page
- New 'Post-processing & warm-start' sidebar expander with two toggles:
  * Greedy 1-flip polish (default ON, gracefully no-ops on Spin /
    Categorical problems where Q_mat is unavailable).
  * BFS 2-color warm-start (graph QUBOs only, falls back to random init
    if the problem does not expose nx_graph / graph).
- Wire both into the qqa.anneal call via the new (initial_state=,
  polish=) parameters.
- Score card now surfaces a 'pre-polish loss = ... (polish improved by
  Δ)' badge whenever polish actually moved the needle, so users can
  see the contribution at a glance.
- Run history snapshots both flags so the Visualize / Compare pages
  see a faithful record of what produced each result.

Home page
- Register the new MinimumDominatingSet (Graph family) and
  BalancedGraphPartition (Categorical / assignment) problems so the
  UI catalog matches the CLI/Python API one-to-one.
- bgp uses the existing graph-degree slider plus a num_category
  ('partitions K') and a balance-penalty slider.

_common
- build_problem dispatches the two new kinds.
- render_score_card grows an optional pre_polish_loss kwarg.

Tests
- Add three AppTest regressions: the Solve sidebar must expose both
  toggles with the documented defaults, the Home catalog must list
  Minimum Dominating Set and Balanced Graph Partition, and the full
  Solve flow must succeed end-to-end on min_dominating_set.

Made-with: Cursor

Author: Yuma-Ichikawa

app/_common.py

@@ -893,8 +893,27 @@ def hero_badges() -> None:
     )
 
 
-def render_score_card(score: dict, raw_loss: float | None = None) -> None:
-    """Render the big problem-specific score tile used by the Solve page."""
+def render_score_card(
+    score: dict,
+    raw_loss: float | None = None,
+    *,
+    pre_polish_loss: float | None = None,
+) -> None:
+    """Render the big problem-specific score tile used by the Solve page.
+
+    Parameters
+    ----------
+    score:
+        Output of ``problem.score_summary``.
+    raw_loss:
+        Optional raw ``loss_fn`` value (after polish, since ``anneal``
+        replaces ``best_obj`` with the polished value).
+    pre_polish_loss:
+        Optional ``loss_fn`` value of the *un-polished* annealer winner.
+        Displayed as a small "before polish" badge whenever it is
+        strictly worse than ``raw_loss`` so the user can see how much
+        :func:`qqa.polish.greedy_one_flip` contributed.
+    """
     if not score:
         return
     feas = score.get("feasible", True)
@@ -908,12 +927,25 @@ def render_score_card(score: dict, raw_loss: float | None = None) -> None:
     unit = score.get("unit", "")
     unit_html = f'<span class="unit">{unit}</span>' if unit else ""
     raw_html = f'<div class="raw">raw loss = {raw_loss:.4g}</div>' if raw_loss is not None else ""
+    polish_html = ""
+    if (
+        pre_polish_loss is not None
+        and raw_loss is not None
+        # Only surface the line when polish actually moved the needle.
+        and pre_polish_loss > raw_loss + 1e-9
+    ):
+        delta = pre_polish_loss - raw_loss
+        polish_html = (
+            f'<div class="raw">pre-polish loss = {pre_polish_loss:.4g} '
+            f"(polish improved by {delta:.4g})</div>"
+        )
     value_cls = "value" if feas else "value infeasible"
     st.markdown(
         f'<div class="qqa-score">'
         f'<div class="label">{score.get("label", "score")} · {badge}</div>'
         f'<div class="{value_cls}">{value_s}{unit_html}</div>'
         f"{raw_html}"
+        f"{polish_html}"
         "</div>",
         unsafe_allow_html=True,
     )
@@ -951,7 +983,16 @@ def build_problem(cfg: dict) -> Any:
 
     size = int(cfg["size"])
     seed = cfg["seed"]
-    if kind in {"mis", "maxcut", "maxclique", "coloring", "vertex_cover", "graph_bisection"}:
+    if kind in {
+        "mis",
+        "maxcut",
+        "maxclique",
+        "coloring",
+        "vertex_cover",
+        "graph_bisection",
+        "min_dominating_set",
+        "bgp",
+    }:
         return _build_graph_problem(kind, size, seed, device, extra)
     if kind == "ising1d":
         return _safe_call(qqa.Ising1D, N=size, device=device)
@@ -1054,6 +1095,16 @@ def _build_graph_problem(kind: str, size: int, seed: int, device: str, extra: di
             balance_penalty=float(extra.get("balance_penalty", 2.0)),
             device=device,
         )
+    if kind == "min_dominating_set":
+        return _safe_call(qqa.MinimumDominatingSet, g, device=device)
+    if kind == "bgp":
+        return _safe_call(
+            qqa.BalancedGraphPartition,
+            g,
+            num_category=int(extra.get("num_category", 3)),
+            penalty=float(extra.get("balance_penalty", 5e-4)),
+            device=device,
+        )
     raise ValueError(f"Unknown graph-problem kind {kind!r}")
 
 

app/pages/1_Solve.py

@@ -170,6 +170,36 @@ def _apply_preset(name: str) -> None:
             help="Repulsion strength between replicas (0 = independent runs).",
         )
 
+    with st.expander("Post-processing & warm-start", expanded=False):
+        polish = st.toggle(
+            "Greedy 1-flip polish (recommended)",
+            value=st.session_state.get("polish", True),
+            key="polish",
+            help=(
+                "Run a deterministic single-bit local search on the "
+                "annealer's winner. Costs O(N · #flips) and is silently "
+                "skipped on non-QUBO problems (Spin / Categorical). "
+                "Typical free improvement of +10 to +90 on hard MaxCut / "
+                "MIS / VertexCover instances."
+            ),
+        )
+        # Warm-start only makes sense when the problem exposes a NetworkX
+        # graph the BFS heuristic can read. We surface the toggle for *any*
+        # graph problem and gate the actual call on the problem object at
+        # runtime — this keeps the sidebar layout stable across kinds.
+        warm_start = st.toggle(
+            "BFS 2-color warm-start (graph QUBOs only)",
+            value=st.session_state.get("warm_start", False),
+            key="warm_start",
+            help=(
+                "Seed every replica with the BFS-tree 2-coloring of the "
+                "graph (a near-optimal cut on bipartite components). "
+                "Particularly effective on near-bipartite Max-Cut "
+                "instances (G-set G70 / G77). Has no effect on non-graph "
+                "problems."
+            ),
+        )
+
     with st.expander("Display", expanded=False):
         update_every = st.slider(
             "UI update every (epochs)",
@@ -444,6 +474,24 @@ def on_epoch_end(self, state: CallbackState) -> None:
     )
     pop_tracker = PopulationTracker(stride=max(1, update_every), record_x=True)
 
+    # Build the warm-start seed when requested AND the problem exposes a
+    # graph attribute. Falls back silently otherwise so the toggle never
+    # crashes a non-graph run.
+    initial_state = None
+    if warm_start:
+        graph = getattr(problem, "nx_graph", None) or getattr(problem, "graph", None)
+        if graph is not None:
+            try:
+                initial_state = qqa.warmstart.bfs_2color(graph).to(cfg["device"])
+                st.caption(
+                    f"warm-started {sol_size} replicas from BFS 2-coloring "
+                    f"({initial_state.shape[0]} bits)."
+                )
+            except Exception as exc:
+                # Don't fail the whole run if the heuristic chokes on an
+                # unusual graph; just log and fall back to the random init.
+                st.warning(f"warm-start unavailable: {exc}")
+
     try:
         result = qqa.anneal(
             problem,
@@ -457,6 +505,8 @@ def on_epoch_end(self, state: CallbackState) -> None:
             num_epochs=epochs,
             device=cfg["device"],
             callbacks=[cb, pop_tracker],
+            initial_state=initial_state,
+            polish=polish,
             verbose=False,
         )
     except Exception as e:
@@ -468,10 +518,16 @@ def on_epoch_end(self, state: CallbackState) -> None:
     raw = (
         result.best_obj
         if isinstance(result.best_obj, float)
-        else float(__import__("numpy").asarray(result.best_obj).mean())
+        else float(np.asarray(result.best_obj).mean())
+    )
+    # The callback tracks the *un-polished* running best (it fires inside
+    # the annealing loop, before greedy_one_flip runs). Surface that here
+    # so users can see how much polish contributed when it actually fired.
+    pre_polish = (
+        cb.best_disc[-1] if (polish and result.polished_sol is not None and cb.best_disc) else None
     )
     with score_holder.container():
-        render_score_card(result.score, raw_loss=raw)
+        render_score_card(result.score, raw_loss=raw, pre_polish_loss=pre_polish)
     st.session_state.setdefault("results", []).append(
         {
             "cfg": dict(cfg),
@@ -484,6 +540,8 @@ def on_epoch_end(self, state: CallbackState) -> None:
                 "curve_rate": curve_rate,
                 "div_param": div_param,
                 "num_epochs": epochs,
+                "polish": polish,
+                "warm_start": warm_start,
             },
             "result": result,
         }

app/streamlit_app.py

@@ -136,9 +136,11 @@
                 ("maxclique", "Max Clique"),
                 ("vertex_cover", "Vertex Cover"),
                 ("graph_bisection", "Graph bisection"),
+                ("min_dominating_set", "Minimum Dominating Set"),
             ],
             "Categorical / assignment": [
                 ("coloring", "Graph coloring"),
+                ("bgp", "Balanced graph partition (K-way)"),
                 ("tsp", "Travelling Salesman (TSP)"),
                 ("qap", "Quadratic Assignment (QAP)"),
                 ("nqueens", "N-Queens"),
@@ -181,11 +183,24 @@
         seed = st.number_input("Seed", min_value=0, max_value=10_000, value=0)
 
         # Per-problem auxiliary controls.
-        if problem_kind in {"mis", "maxcut", "maxclique", "vertex_cover", "graph_bisection"}:
+        if problem_kind in {
+            "mis",
+            "maxcut",
+            "maxclique",
+            "vertex_cover",
+            "graph_bisection",
+            "min_dominating_set",
+        }:
             extra["graph_d"] = st.slider("Random-regular degree d", 2, 8, 3)
         if problem_kind == "coloring":
             extra["num_category"] = st.slider("Number of colours K", 2, 6, 3)
             extra["graph_d"] = st.slider("Random-regular degree d", 2, 8, 3)
+        if problem_kind == "bgp":
+            extra["num_category"] = st.slider("Number of partitions K", 2, 8, 3)
+            extra["graph_d"] = st.slider("Random-regular degree d", 2, 8, 3)
+            extra["balance_penalty"] = st.slider(
+                "Balance penalty", 0.0001, 0.01, 0.0005, 0.0001, format="%.4f"
+            )
         if problem_kind == "ea":
             extra["dim"] = st.selectbox("Lattice dim", (2, 3), index=1)
         if problem_kind == "perceptron":

tests/test_gui_apptest.py

@@ -392,6 +392,92 @@ def test_compare_page_shootout_mode_runs_pqqa_vs_sa():
     )
 
 
+def test_solve_page_exposes_polish_and_warmstart_toggles():
+    """The Solve page must surface the post-processing & warm-start toggles
+    introduced in the v0.5 release. Polish defaults to ON; warm-start
+    defaults to OFF (only useful for graph problems)."""
+    at = AppTest.from_file(str(PAGE_DIR / "1_Solve.py"), default_timeout=60)
+    at.session_state["problem_config"] = {
+        "kind": "maxcut",
+        "size": 16,
+        "seed": 0,
+        "device": "cpu",
+        "extra": {"graph_d": 3},
+    }
+    at.run()
+    assert not at.exception, at.exception
+    toggle_labels = [t.label for t in at.sidebar.toggle]
+    assert any("polish" in lab.lower() for lab in toggle_labels), (
+        f"Polish toggle missing; got {toggle_labels!r}"
+    )
+    assert any(
+        "warm-start" in lab.lower() or "warm start" in lab.lower() for lab in toggle_labels
+    ), f"Warm-start toggle missing; got {toggle_labels!r}"
+    polish_toggles = [t for t in at.sidebar.toggle if "polish" in t.label.lower()]
+    assert polish_toggles[0].value is True, "Polish toggle should default to ON"
+    warm_toggles = [
+        t
+        for t in at.sidebar.toggle
+        if "warm-start" in t.label.lower() or "warm start" in t.label.lower()
+    ]
+    assert warm_toggles[0].value is False, "Warm-start toggle should default to OFF"
+
+
+def test_home_page_lists_min_dominating_set_and_bgp():
+    """The new problem catalog entries (MinimumDominatingSet,
+    BalancedGraphPartition) must be selectable from the Home page so the
+    UI exercises the same registry as the CLI."""
+    at = AppTest.from_file(str(APP), default_timeout=60)
+    at.run()
+    assert not at.exception, at.exception
+    selectboxes = at.sidebar.selectbox
+    family_select = next((s for s in selectboxes if "family" in s.label.lower()), None)
+    problem_select = next((s for s in selectboxes if s.label == "Problem"), None)
+    assert family_select is not None and problem_select is not None, (
+        f"Family/Problem selectboxes missing; got {[s.label for s in selectboxes]!r}"
+    )
+    # The dropdown is populated with human-readable labels via
+    # ``format_func``, so search the rendered strings rather than the raw
+    # kind keys. Default family is "Graph (binary QUBO)".
+    graph_options = [str(o).lower() for o in (problem_select.options or [])]
+    assert any("dominating" in o for o in graph_options), (
+        f"Minimum Dominating Set missing from Graph problems; got {graph_options!r}"
+    )
+    family_select.set_value("Categorical / assignment")
+    at.run()
+    assert not at.exception, at.exception
+    problem_select = next(s for s in at.sidebar.selectbox if s.label == "Problem")
+    cat_options = [str(o).lower() for o in (problem_select.options or [])]
+    assert any("balanced" in o or "partition" in o for o in cat_options), (
+        f"Balanced Graph Partition missing from Categorical problems; got {cat_options!r}"
+    )
+
+
+def test_solve_runs_with_min_dominating_set_default():
+    """End-to-end smoke for the new MinimumDominatingSet problem under
+    the same UI flow used by every other graph QUBO."""
+    at = AppTest.from_file(str(PAGE_DIR / "1_Solve.py"), default_timeout=120)
+    at.session_state["problem_config"] = {
+        "kind": "min_dominating_set",
+        "size": 16,
+        "seed": 0,
+        "device": "cpu",
+        "extra": {"graph_d": 3},
+    }
+    at.run()
+    assert not at.exception, at.exception
+    _set_slider(at, "sol_size", 8)
+    _set_slider(at, "epochs", 100)
+    _set_slider(at, "UI update every", 10)
+    at.run()
+    assert not at.exception, at.exception
+    runs = [b for b in at.button if "Run" in b.label]
+    assert runs, "Run QQA button missing"
+    runs[0].click()
+    at.run()
+    assert not at.exception, at.exception
+
+
 def test_solution_viz_smoke_across_problem_kinds(tmp_path):
     """Every registered renderer in ``_solution_viz`` must accept a real
     ``(problem, result, cfg)`` triple without raising.