fix(app): drop unsafe plotly_chart key, custom problem on by default

Crit-fix

- The Solve page crashed with ``StreamlitDuplicateElementKey`` on the
  second callback tick: the previous "no flash" tweak attached a
  stable ``key="qqa_solve_dynamics"`` to a ``placeholder.plotly_chart``
  call invoked many times within one script run, and Streamlit
  registered each invocation as a duplicate widget. The three
  live-update charts (dynamics, parallel population, diversity) now
  call ``placeholder.plotly_chart(fig, theme=None,
  config={"displayModeBar": False})`` with **no key**. ``theme=None``
  skips Streamlit's per-call theme injection (the figure already
  carries our palette via ``plotly_layout``), which makes the redraw
  cheaper and noticeably reduces flash; hiding the modebar removes
  the modebar/title overlap that was visible in the user's
  screenshot.

Custom-problem flow now first-class

- ``ALLOW_CUSTOM`` defaults to **True** so the editor is reachable
  from the deployed UI without setting a server-side env var
  (``QQA_ALLOW_CUSTOM=0`` remains as an opt-out for shared hosting).
- A curated example library lives in ``_common.CUSTOM_EXAMPLES``
  (Spin glass, Number partitioning, Weighted MaxCut, Ferromagnetic
  Ising, Custom QUBO, Random 3-SAT). The editor surface adds a
  dropdown + "Load example" button that swaps the snippet with one
  click, plus a prominent ⚠️ banner spelling out that the snippet is
  ``exec``'d in the Streamlit process.

Solve sidebar usability

- 9 sliders → grouped into four ``st.expander``s (Population &
  schedule, Optimiser, Cooling / diversity, Display). Every slider
  now carries a ``help=`` tooltip and a stable ``key=``.
- Three preset buttons at the top — 🏃 Fast smoke / 🎯 Default /
  🔬 Thorough — write tuples into ``st.session_state`` and ``rerun()``
  so the new defaults take effect immediately.

Plotly polish

- ``plotly_layout`` bumps top margin from 48 to 64 (and right margin
  to 28) so the title never collides with the Plotly modebar.

Regression tests

- ``test_solve_runs_with_default_mis`` clicks Run on the **default**
  MIS problem with a small epoch budget; would have caught the
  duplicate-key crash on the first tick.
- ``test_custom_problem_available_by_default`` verifies that without
  ``QQA_ALLOW_CUSTOM`` the toggle and the curated example dropdown
  both render.

Verified locally

- ``uv run ruff check src tests scripts app`` — clean.
- ``uv run ruff format --check src tests scripts app`` — clean.
- ``uv run pytest -q`` — 55 passed, 1 skipped (was 53; +2 new GUI
  regression tests).

Author: Yuma-Ichikawa

app/_common.py

@@ -42,6 +42,85 @@ def loss_fn(s):
     return -0.5 * torch.einsum("bi,ij,bj->b", s, J, s)
 '''
 
+# Curated example library shown in the Custom-problem editor's "Load
+# example" dropdown. Each entry is a self-contained snippet that defines
+# ``loss_fn(x)`` for one variable kind.
+CUSTOM_EXAMPLES: dict[str, str] = {
+    "Spin glass (default SK)": DEFAULT_CUSTOM_SNIPPET,
+    "Number partitioning (spin)": '''import torch
+
+N = 32
+g = torch.Generator().manual_seed(0)
+a = torch.randint(1, 100, (N,), generator=g).float()
+
+
+def loss_fn(s):
+    """Minimise the squared imbalance Σ a_i s_i with s ∈ {-1,+1}^N."""
+    return (s @ a) ** 2
+''',
+    "Weighted MaxCut (binary)": '''import torch
+
+N = 32
+g = torch.Generator().manual_seed(0)
+W = torch.rand(N, N, generator=g)
+W = (W + W.T) / 2
+W.fill_diagonal_(0.0)
+
+
+def loss_fn(x):
+    """Maximise Σ_{i<j} W_ij (x_i + x_j - 2 x_i x_j) — a weighted MaxCut.
+
+    The annealer minimises, so we negate.
+    """
+    cut = torch.einsum("ij,bi,bj->b", W, x, 1 - x)
+    return -cut
+''',
+    "Ferromagnetic Ising chain": '''import torch
+
+N = 64
+J = 1.0
+h = 0.0
+
+
+def loss_fn(s):
+    """1-D ferromagnet: -J Σ s_i s_{i+1} - h Σ s_i, s ∈ {-1,+1}."""
+    return -J * (s[:, :-1] * s[:, 1:]).sum(dim=1) - h * s.sum(dim=1)
+''',
+    "Custom QUBO from a matrix": '''import torch
+
+# Replace Q with your own (N×N) matrix. The energy is x^T Q x.
+N = 24
+g = torch.Generator().manual_seed(7)
+Q = torch.randn(N, N, generator=g)
+Q = (Q + Q.T) / 2
+
+
+def loss_fn(x):
+    """Generic QUBO loss for binary x ∈ {0,1}^N."""
+    return torch.einsum("ij,bi,bj->b", Q, x, x)
+''',
+    "Random 3-SAT clause loss (binary)": """import torch
+
+N = 30
+M = 90  # clauses
+g = torch.Generator().manual_seed(0)
+lit = torch.randint(0, 2 * N, (M, 3), generator=g)  # variable-with-sign codes
+sign = (lit % 2 == 0).float() * 2.0 - 1.0  # +1 if positive literal, -1 if negated
+var = lit // 2
+
+
+def loss_fn(x):
+    # Map x ∈ {0,1} to ±1 literal evaluations.
+    spins = 2 * x - 1.0  # (B, N)
+    chosen = spins[:, var]  # (B, M, 3)
+    eval_lit = chosen * sign  # +1 if literal satisfied
+    # Clause unsatisfied iff every literal is -1, i.e. product == -1
+    # easier: clause "value" = max over literals; we approximate with mean.
+    sat = ((eval_lit + 1) / 2).max(dim=-1).values  # (B, M)
+    return (1.0 - sat).sum(dim=-1)
+""",
+}
+
 
 # ---------------------------------------------------------------------------
 # Theme helpers
@@ -134,14 +213,16 @@ def plotly_layout(theme: str | None = None, **overrides) -> dict:
         "font": {"family": "Inter, -apple-system, sans-serif", "size": 13, "color": p["text"]},
         "title_font": {
             "family": "'Source Serif 4', Georgia, serif",
-            "size": 17,
+            "size": 16,
             "color": p["text"],
         },
         "colorway": p["palette"],
         "xaxis": {"gridcolor": p["grid"], "linecolor": p["border"], "zerolinecolor": p["grid"]},
         "yaxis": {"gridcolor": p["grid"], "linecolor": p["border"], "zerolinecolor": p["grid"]},
         "legend": {"bgcolor": "rgba(0,0,0,0)", "bordercolor": p["border"], "borderwidth": 0.5},
-        "margin": {"l": 50, "r": 20, "t": 48, "b": 46},
+        # Top margin keeps the title clear of Plotly's modebar (which lives
+        # in the top-right corner). Was 48, and even modest titles collided.
+        "margin": {"l": 56, "r": 28, "t": 64, "b": 50},
     }
     base.update(overrides)
     return base

app/pages/1_Solve.py

@@ -43,17 +43,131 @@
     f"device: **{cfg['device']}** | seed: **{cfg['seed']}**"
 )
 
+# Hyper-parameter presets — each tuple is
+# (sol_size, epochs, learning_rate, temp, min_bg, max_bg, curve_rate,
+#  div_param, update_every).
+_PRESETS = {
+    "🏃  Fast smoke": (32, 200, 1.0, 0.0, -2.0, 0.1, 2, 0.0, 10),
+    "🎯  Default": (64, 1000, 1.0, 0.0, -2.0, 0.1, 2, 0.0, 20),
+    "🔬  Thorough": (128, 3000, 0.7, 0.05, -3.0, 0.2, 4, 0.0, 50),
+}
+
+
+def _apply_preset(name: str) -> None:
+    """Write preset values into ``st.session_state`` so the widgets pick
+    them up on the next rerun."""
+    keys = (
+        "sol_size",
+        "epochs",
+        "learning_rate",
+        "temp",
+        "min_bg",
+        "max_bg",
+        "curve_rate",
+        "div_param",
+        "update_every",
+    )
+    for k, v in zip(keys, _PRESETS[name], strict=True):
+        st.session_state[k] = v
+
+
 with st.sidebar:
     st.header("2 · QQA hyper-parameters")
-    sol_size = st.slider("sol_size (parallel population)", 4, 400, 64)
-    epochs = st.slider("epochs", 100, 5000, 1000, step=100)
-    learning_rate = st.slider("learning rate", 0.05, 3.0, 1.0, 0.05)
-    temp = st.slider("Langevin temperature", 0.0, 1.0, 0.0, 0.01)
-    min_bg = st.slider("min bg", -5.0, 0.0, -2.0, 0.1)
-    max_bg = st.slider("max bg", 0.0, 2.0, 0.1, 0.1)
-    curve_rate = st.selectbox("curve rate", (2, 4, 6), index=0)
-    div_param = st.slider("div_param", 0.0, 1.0, 0.0, 0.01)
-    update_every = st.slider("UI update every (epochs)", 1, 200, 20)
+    preset_name = st.radio(
+        "Preset",
+        list(_PRESETS),
+        index=1,
+        horizontal=False,
+        help="Quickly seed every slider below. You can still tweak any value.",
+    )
+    if st.button("Apply preset", width="stretch"):
+        _apply_preset(preset_name)
+        st.rerun()
+
+    with st.expander("Population & schedule", expanded=True):
+        sol_size = st.slider(
+            "sol_size",
+            4,
+            400,
+            st.session_state.get("sol_size", 64),
+            key="sol_size",
+            help="Number of parallel replicas annealed in lockstep.",
+        )
+        epochs = st.slider(
+            "epochs",
+            100,
+            5000,
+            st.session_state.get("epochs", 1000),
+            step=100,
+            key="epochs",
+            help="Total annealing iterations.",
+        )
+        curve_rate = st.selectbox(
+            "curve rate",
+            (2, 4, 6),
+            index=(2, 4, 6).index(st.session_state.get("curve_rate", 2)),
+            key="curve_rate",
+            help="Steepness of the bias schedule (higher = more abrupt).",
+        )
+
+    with st.expander("Optimiser", expanded=False):
+        learning_rate = st.slider(
+            "learning rate",
+            0.05,
+            3.0,
+            st.session_state.get("learning_rate", 1.0),
+            0.05,
+            key="learning_rate",
+            help="Adam step size for the relaxed variables.",
+        )
+        temp = st.slider(
+            "Langevin temperature",
+            0.0,
+            1.0,
+            st.session_state.get("temp", 0.0),
+            0.01,
+            key="temp",
+            help="Magnitude of the stochastic noise injected each step (0 = deterministic).",
+        )
+
+    with st.expander("Cooling / diversity", expanded=False):
+        min_bg = st.slider(
+            "min bg",
+            -5.0,
+            0.0,
+            st.session_state.get("min_bg", -2.0),
+            0.1,
+            key="min_bg",
+            help="Initial bias-gain (smooth, exploratory).",
+        )
+        max_bg = st.slider(
+            "max bg",
+            0.0,
+            2.0,
+            st.session_state.get("max_bg", 0.1),
+            0.1,
+            key="max_bg",
+            help="Final bias-gain (sharp, near-discrete).",
+        )
+        div_param = st.slider(
+            "div_param",
+            0.0,
+            1.0,
+            st.session_state.get("div_param", 0.0),
+            0.01,
+            key="div_param",
+            help="Repulsion strength between replicas (0 = independent runs).",
+        )
+
+    with st.expander("Display", expanded=False):
+        update_every = st.slider(
+            "UI update every (epochs)",
+            1,
+            200,
+            st.session_state.get("update_every", 20),
+            key="update_every",
+            help="Lower = smoother animation but slower wall-clock; higher = faster.",
+        )
 
 
 class StreamlitCallback(Callback):
@@ -154,7 +268,16 @@ def on_epoch_end(self, state: CallbackState) -> None:
                 legend={"x": 0.01, "y": 0.02, "bgcolor": "rgba(255,255,255,0.6)"},
             )
         )
-        self.chart_holder.plotly_chart(fig, width="stretch", key="qqa_solve_dynamics")
+        # IMPORTANT: do NOT pass ``key=`` here. ``st.empty().plotly_chart`` is
+        # invoked many times within one script run (once per ``update_every``
+        # epochs); a stable key would collide with itself and trip
+        # StreamlitDuplicateElementKey. ``theme=None`` skips Streamlit's
+        # per-call theme-injection step (the figure already carries our
+        # palette via ``plotly_layout``) which makes the redraw cheaper and
+        # noticeably reduces flash on the live charts.
+        self.chart_holder.plotly_chart(
+            fig, width="stretch", theme=None, config={"displayModeBar": False}
+        )
 
         # --- Population heatmap: replicas sorted by best-so-far --------
         pop = np.stack(self.pop, axis=1)  # (sol_size, T)
@@ -200,7 +323,9 @@ def on_epoch_end(self, state: CallbackState) -> None:
                 legend={"x": 0.01, "y": 0.99, "bgcolor": "rgba(255,255,255,0.6)"},
             )
         )
-        self.pop_holder.plotly_chart(pop_fig, width="stretch", key="qqa_solve_population")
+        self.pop_holder.plotly_chart(
+            pop_fig, width="stretch", theme=None, config={"displayModeBar": False}
+        )
 
         # --- Diversity curve: std across replicas vs epoch --------------
         div_fig = go.Figure()
@@ -224,7 +349,9 @@ def on_epoch_end(self, state: CallbackState) -> None:
                 showlegend=False,
             )
         )
-        self.diversity_holder.plotly_chart(div_fig, width="stretch", key="qqa_solve_diversity")
+        self.diversity_holder.plotly_chart(
+            div_fig, width="stretch", theme=None, config={"displayModeBar": False}
+        )
 
 
 run = st.button("▶  Run QQA", type="primary")

app/streamlit_app.py

@@ -22,6 +22,7 @@
 
 import streamlit as st  # noqa: E402
 from _common import (  # noqa: E402
+    CUSTOM_EXAMPLES,
     DEFAULT_CUSTOM_SNIPPET,
     apply_theme,
     build_problem,
@@ -34,11 +35,12 @@
 
 import qqa  # noqa: E402
 
-# The custom-problem editor runs user-supplied Python via ``exec``. Disable
-# it on public deployments by setting ``QQA_ALLOW_CUSTOM=0`` (this is the
-# default on Streamlit Community Cloud / Hugging Face Spaces). Set it to
-# ``1`` to re-enable on a trusted machine.
-ALLOW_CUSTOM = os.getenv("QQA_ALLOW_CUSTOM", "0") == "1"
+# The custom-problem editor runs user-supplied Python via ``exec`` inside
+# the Streamlit process. We expose it from the UI by default — this is a
+# public research tool, not a multi-tenant service — but make the security
+# trade-off explicit via a banner and an opt-out env var
+# (``QQA_ALLOW_CUSTOM=0`` hides the editor on shared deployments).
+ALLOW_CUSTOM = os.getenv("QQA_ALLOW_CUSTOM", "1") == "1"
 
 st.set_page_config(
     page_title="QQA dashboard",
@@ -74,7 +76,11 @@
         use_custom = st.toggle(
             "Use custom problem",
             value=False,
-            help="Plug in your own loss_fn directly from this UI.",
+            help=(
+                "Plug in your own loss_fn directly from this UI. The code "
+                "runs in this Streamlit process — only paste code you trust."
+            ),
+            key="use_custom",
         )
     else:
         use_custom = False
@@ -202,12 +208,35 @@
 # ---------------------------------------------------------------------------
 if use_custom:
     st.subheader("Custom loss editor")
+    st.warning(
+        "⚠️  The snippet below is executed via Python `exec` inside this "
+        "Streamlit process. Only paste code you trust; the editor is "
+        "intentionally exposed for research use, not for hosting "
+        "untrusted user code.",
+        icon="⚠️",
+    )
     st.markdown(
         "Define a function named `loss_fn(x)` that maps a batched configuration "
         "tensor to a `(B,)` loss vector. The namespace already has `torch` and "
         "`np` (numpy) imported. Any constants (couplings, patterns, ...) you "
         "declare at module scope are captured by closure."
     )
+
+    example_keys = list(CUSTOM_EXAMPLES)
+    col_l, col_r = st.columns([2, 1])
+    with col_l:
+        example_choice = st.selectbox(
+            "Load example",
+            example_keys,
+            index=0,
+            help="Replace the editor with a fully-working snippet.",
+        )
+    with col_r:
+        st.write("")
+        if st.button("Load example", width="stretch"):
+            st.session_state["custom_source"] = CUSTOM_EXAMPLES[example_choice]
+            st.rerun()
+
     source = st.text_area(
         "Snippet",
         value=st.session_state.get("custom_source", DEFAULT_CUSTOM_SNIPPET),