feat(bench): rename HF dataset to qqa4co-bench + add MaxCut G-set family

* HF dataset id `Yuma-Ichikawsa/discs-co-bench` renamed to
  `Yuma-Ichikawsa/qqa4co-bench` via `HfApi.move_repo` (DISCS prefix
  was actively misleading after four other families landed). Old id
  keeps a 30-day redirect. Every in-repo reference (README, docs,
  setup scripts, data/*/README, plot footer, HF card) updated.

* New MaxCut G-set family (71 graphs: G1..G67 + G70/G72/G77/G81)
  with best-known cuts from Benlic & Hao 2013, Matsuda 2018 and
  Ichikawa NeurIPS 2024. Covers the canonical annealing / PI-GNN /
  PQQA benchmark universe. Shipped via:
    - `scripts/fetch_gset_data.py` (download + pickle + manifest)
    - `qqa.datasets.gset()` loader
    - `--suite gset` in `scripts/bench_discs.py`
    - new catalog branch in `_build_catalog`
    - full `gset/` payload uploaded to HF (~30 MB)

* `qqa bench-plot --output data/fig/x.png` no longer mangles the path
  into `bench_results/data/fig/x.png`; only bare filenames get the
  default-dir prefix (cli.py + bench.py both fixed, regression test
  exists in tests/test_bench_api.py).

* Real benchmark visualisation: ran `qqa bench-run` on gset (5),
  coloring (4), ea3d (3) on CPU and re-rendered
  `data/fig/gallery/bench_report_example.png` from real data instead
  of a synthetic mock (91.7% feasibility, 0.979 mean ApR on the gset
  subset after 300 epochs @ sol-size 64).

* New `tests/test_docs_assets.py` — 24 parametrised cases — walks
  every markdown file under `docs/` and asserts image links either
  resolve inside the doc root or are absolute URLs. Catches the same
  class of bug that broke CI run 24658520429 in ~50 ms locally.

* Three new unit tests in test_new_benchmark_loaders.py covering the
  gset loader, its `limit=` knob, and the bench_discs catalog
  integration. 371 tests pass, 2 skipped (unrelated torch_geometric
  / plotly guards), ruff check + format green, mkdocs --strict green.

Author: Yuma Ichikawa

README.md

@@ -22,16 +22,16 @@ with earlier QQA4CO releases (``import qqa``).
   <a href="https://github.com/Yuma-Ichikawa/QQA4CO/discussions"><img src="https://img.shields.io/github/discussions/Yuma-Ichikawa/QQA4CO?logo=github&label=Discussions" alt="GitHub Discussions"></a>
   <a href="https://codecov.io/gh/Yuma-Ichikawa/QQA4CO"><img src="https://codecov.io/gh/Yuma-Ichikawa/QQA4CO/branch/main/graph/badge.svg" alt="Coverage"></a>
   <a href="https://doi.org/10.5281/zenodo.19648231"><img src="https://img.shields.io/badge/DOI-10.5281%2Fzenodo.19648231-1f6feb?logo=doi&logoColor=white" alt="DOI"></a>
-  <a href="https://huggingface.co/datasets/Yuma-Ichikawsa/discs-co-bench"><img src="https://img.shields.io/badge/%F0%9F%A4%97%20Dataset-Yuma--Ichikawsa%2Fdiscs--co--bench-yellow" alt="Hugging Face dataset"></a>
+  <a href="https://huggingface.co/datasets/Yuma-Ichikawsa/qqa4co-bench"><img src="https://img.shields.io/badge/%F0%9F%A4%97%20Dataset-Yuma--Ichikawsa%2Fqqa4co--bench-yellow" alt="Hugging Face dataset"></a>
 </p>
 
 <p align="center">
   <b>Benchmark data &nbsp;·&nbsp;</b>
-  <a href="https://huggingface.co/datasets/Yuma-Ichikawsa/discs-co-bench">
-    <code>huggingface.co/datasets/Yuma-Ichikawsa/discs-co-bench</code>
+  <a href="https://huggingface.co/datasets/Yuma-Ichikawsa/qqa4co-bench">
+    <code>huggingface.co/datasets/Yuma-Ichikawsa/qqa4co-bench</code>
   </a>
   <br>
-  <sub>DISCS (NeurIPS 2023) + Graph Coloring (COLOR) + MIS on d-regular random graphs (PQQA §5.1) + 3D Edwards-Anderson spin glass + Balanced k-way partition — one HF dataset, <code>make bench-all-setup</code> pulls everything.</sub>
+  <sub>DISCS (NeurIPS 2023) + MaxCut G-set (Helmberg & Rendl 2000) + Graph Coloring (COLOR) + MIS on d-regular random graphs (PQQA §5.1) + 3D Edwards-Anderson spin glass + Balanced k-way partition — one HF dataset, <code>make bench-all-setup</code> pulls everything.</sub>
 </p>
 
 <p align="center">
@@ -405,15 +405,16 @@ qqa gui                                  # opens http://localhost:8501
 
 Run `qqa <command> --help` for the full option list.
 
-### All CO benchmarks in one command (DISCS + PQQA + EA3D)
+### All CO benchmarks in one command (DISCS + G-set + PQQA + EA3D)
 
 Every benchmark instance lives on the Hugging Face Hub:
 
-> **Dataset:** [`huggingface.co/datasets/Yuma-Ichikawsa/discs-co-bench`](https://huggingface.co/datasets/Yuma-Ichikawsa/discs-co-bench)
-> &nbsp;&nbsp;·&nbsp;&nbsp; DISCS (MaxCut/MIS/MaxClique/NormCut) + Graph
-> Coloring (COLOR) + MIS on d-regular random graphs (PQQA §5.1) + 3D
-> Edwards-Anderson spin glass + Balanced k-way partition — **one repo,
-> `make bench-all-setup` pulls everything**.
+> **Dataset:** [`huggingface.co/datasets/Yuma-Ichikawsa/qqa4co-bench`](https://huggingface.co/datasets/Yuma-Ichikawsa/qqa4co-bench)
+> &nbsp;&nbsp;·&nbsp;&nbsp; DISCS (MaxCut / MIS / MaxClique / NormCut) +
+> **MaxCut G-set (Helmberg & Rendl 2000, 71 graphs G1-G67 + G70/72/77/81)** +
+> Graph Coloring (COLOR) + MIS on d-regular random graphs (PQQA §5.1) +
+> 3D Edwards-Anderson spin glass + Balanced k-way partition — **one
+> repo, `make bench-all-setup` pulls everything**.
 
 Third parties benchmark a solver in **three one-liners**:
 

app/pages/2_Visualize.py

@@ -148,7 +148,7 @@ class PAResult:  # type: ignore[no-redef]
     _ordered_keys = _UNIVERSAL_TAB_KEYS + _PQQA_TAB_KEYS + [_TREE_TAB_KEY]
 
 _tabs = st.tabs([_TAB_LABELS[k] for k in _ordered_keys])
-_tab_by_key: dict[str, "st.delta_generator.DeltaGenerator"] = dict(
+_tab_by_key: dict[str, st.delta_generator.DeltaGenerator] = dict(
     zip(_ordered_keys, _tabs, strict=True)
 )
 

data/coloring/README.md

@@ -37,6 +37,6 @@ Everything below `.gitignore` is re-generated locally by:
 python scripts/generate_coloring_instances.py
 ```
 
-Upstream distribution: `yuma-ichikawa/discs-co-bench` on the Hugging Face
+Upstream distribution: `Yuma-Ichikawsa/qqa4co-bench` on the Hugging Face
 Hub (same repo as DISCS; see `data/discs/README.md` for credentials /
 fallbacks).

data/discs/README.md

@@ -36,7 +36,7 @@ make bench-discs SUITE=mis-satlib BACKEND=qqa DEVICE=cuda
 That is it. The setup script will:
 
 1. **Download** the prebuilt dataset from the Hugging Face Hub
-   (`yuma-ichikawa/discs-co-bench`, override with `DISCS_HF_REPO_ID=...`) —
+   (`Yuma-Ichikawsa/qqa4co-bench`, override with `DISCS_HF_REPO_ID=...`) —
    primary source, free, no auth required.
 2. **Or fall back** to the original Google Drive tarball
    (`DISCS-DATA.tar.gz`, ~6.7 GB) and extract just the `DISCS-DATA/sco/`
@@ -127,7 +127,7 @@ data/discs/
 
 ### Why Parquet for distribution (Hugging Face)?
 
-- Hugging Face Datasets' default; `load_dataset("user/discs-co-bench")` works
+- Hugging Face Datasets' default; `load_dataset("user/qqa4co-bench")` works
   out-of-the-box, with streaming for the large MIS-ER-10k subset.
 - Compresses ~3-5× tighter than per-file pickles.
 - Survives format evolution: edge_index columns are forwards-compatible.

data/ea3d/README.md

@@ -41,5 +41,5 @@ against this published ground-state reference when available.
 python scripts/generate_ea3d_instances.py
 ```
 
-Upstream distribution: `yuma-ichikawa/discs-co-bench` on the Hugging Face
+Upstream distribution: `Yuma-Ichikawsa/qqa4co-bench` on the Hugging Face
 Hub.

data/fig/gallery/bench_report_example.png

@@ -1,2 +1,9 @@
+# The actual Gset payload (30 MB) lives on Hugging Face
+# (`Yuma-Ichikawsa/qqa4co-bench` under `gset/`). Pull it with
+# `make bench-all-setup` or `./scripts/setup_benchmarks.sh --only gset`.
+# The raw Stanford text files downloaded by
+# `scripts/fetch_gset_data.py` land under `raw/` and are likewise
+# excluded from version control.
 *
 !.gitignore
+!README.md

data/gset/.gitignore

@@ -0,0 +1,54 @@
+# MaxCut — G-set benchmark
+
+**71 graphs**, best-known cuts tracked, hosted on
+[`Yuma-Ichikawsa/qqa4co-bench`](https://huggingface.co/datasets/Yuma-Ichikawsa/qqa4co-bench)
+under `gset/`.
+
+| size               | instances            | typical n, m                                 |
+| ------------------ | -------------------- | -------------------------------------------- |
+| small              | G1..G21              | n=800, m=800-19 176                          |
+| medium             | G22..G54             | n=1 000..3 000                               |
+| large              | G55..G67             | n=5 000..7 000                               |
+| sparse near-bipart | G70, G72, G77, G81   | n=10 000..20 000                             |
+
+Upstream G68, G69, G71, G73-76, G78-80 are missing from the canonical
+Ye mirror and are therefore not included here (the fetch script skips
+them automatically).
+
+Layout
+
+```
+data/gset/standard/
+    G1.gpickle, G2.gpickle, ..., G81.gpickle
+    manifest.jsonl
+```
+
+Each manifest record carries at least
+
+```json
+{"id": "G70", "file": "G70.gpickle", "nodes": 10000, "edges": 9999,
+ "best_known": 9591,
+ "best_known_source": "Benlic & Hao 2013; Matsuda 2018; Ichikawa NeurIPS 2024",
+ "source_url": "https://web.stanford.edu/~yyye/yyye/Gset/G70",
+ "problem": "maxcut", "graph_type": "gset", "subset": "standard"}
+```
+
+Fetch / regenerate
+
+```bash
+# pull the whole family (30 MB) from Hugging Face
+./scripts/setup_benchmarks.sh --only gset
+
+# …or re-download from Stanford and re-pickle locally (no HF required)
+python scripts/fetch_gset_data.py
+```
+
+Run
+
+```bash
+qqa bench-run --suite gset --instances 5 --output gset.json
+qqa bench-plot bench_results/gset.json --output gset.png
+```
+
+Approximation-ratio convention: ``ratio = found_cut / best_known``
+(higher = better; 1.0 = matches the published upper bound).

data/gset/README.md

@@ -40,5 +40,5 @@ solver benchmark. We ship the `n = 10^4` variant here (covers both
 the Hugging Face Hub mirror stays lean. Reinstate it by passing
 `--nodes 1000000` to `scripts/generate_rrg_instances.py` if needed.
 
-Upstream distribution: `yuma-ichikawa/discs-co-bench` on the Hugging Face
+Upstream distribution: `Yuma-Ichikawsa/qqa4co-bench` on the Hugging Face
 Hub.

data/mis-rrg/README.md

@@ -6,13 +6,14 @@ No edits to the repo or knowledge of its internals are required.
 
 Every benchmark instance lives on the Hugging Face Hub:
 
-> **[`huggingface.co/datasets/Yuma-Ichikawsa/discs-co-bench`](https://huggingface.co/datasets/Yuma-Ichikawsa/discs-co-bench)**
+> **[`huggingface.co/datasets/Yuma-Ichikawsa/qqa4co-bench`](https://huggingface.co/datasets/Yuma-Ichikawsa/qqa4co-bench)**
 
 The dataset bundles the [DISCS](https://arxiv.org/abs/2311.04730) CO
-benchmarks (NeurIPS 2023) plus four extra families described in the
-[PQQA paper](https://openreview.net/forum?id=9EfBeXaXf0): Graph
-Coloring, MIS on `d`-regular random graphs, 3D Edwards-Anderson spin
-glass and Balanced k-way partition.
+benchmarks (NeurIPS 2023), the **MaxCut G-set** superset (71 graphs,
+Helmberg & Rendl 2000 via Yinyu Ye's mirror), and four extra families
+described in the [PQQA paper](https://openreview.net/forum?id=9EfBeXaXf0):
+Graph Coloring, MIS on `d`-regular random graphs, 3D Edwards-Anderson
+spin glass and Balanced k-way partition.
 
 ---
 
@@ -117,6 +118,7 @@ convention differs per family so that the ratio is always in
 |------------------------|----------------|-------------------------------|
 | `mis`, `mis-rrg`       | maximisation   | `solver / best_known`         |
 | `maxcut`, `maxclique`  | maximisation   | `solver / best_known`         |
+| `gset` (MaxCut)        | maximisation   | `solver / best_known`         |
 | `normcut`              | minimisation   | `best_known / solver`         |
 | `coloring`             | conflict count | `feasible` flag only          |
 | `ea3d`                 | energy (≤ 0)   | `solver / best_known`         |