v0.6.0 — Population Annealing + refreshed qqa4co-bench suite

Highlights since v0.5.0

This is a cumulative release absorbing 0.5.1, 0.5.2, 0.5.3 (which
lived in git history but were never uploaded to PyPI).

Major additions

• Population Annealing backend (qqa.population_annealing): parallel
  chain sampling with 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 family via scripts/fetch_gset_data.py and the
  qqa4co-bench dataset.
• 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)
  with stable per-family colours, KPI band, radar, per-subset bars,
  feasibility bars and per-instance violin+strip plots, A/B/C ready.
• Backend-aware Visualize page: 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).
• Up-front PA capability probe in Solve: problems PA cannot sample
  (categorical / structured binary, e.g. TSP, QAP, Coloring, NQueens)
  now show a clear warning banner instead of failing mid-run.

Quality-of-life

• Uniform polish contract across QQA / SA / PA: every backend now
  accepts polish=True/False and exposes a polished_sol, routed
  through the single qqa.polish.apply_polish_if_improves helper.
• _validate_chain_problem now rejects structured BinaryRelaxation
  (e.g. TSP) with an actionable error that steers users to
  qqa.anneal.
• Hugging Face dataset renamed to Yuma-Ichikawa/qqa4co-bench
  (from the legacy discs-co-bench id). scripts/setup_*.sh and all
  docs updated.

Internal / refactor

• qqa.polish.apply_polish_if_improves is the single entry point for
  the greedy 1-flip QUBO polish — removes five copies of the same
  if polish and Q_mat is not None: … block across annealing / SA /
  PA / PI-GNN trainers.
• tests/conftest.py exposes shared fixtures (APP, PAGE_DIR,
  make_problem_config, set_slider); test_gui_apptest.py is 60
  lines lighter.
• app/_common.retheme_plotly + as_numpy replace per-page clones.
• SpinRelaxation.perturb_ now inherits from BinaryRelaxation —
  both share the same [0, 1] latent cube.
• qqa.bench collapsed two near-identical sys.path / importlib
  call sites into one _load_scripts_module(name).

Maintenance

• Renamed LICENCE.txt → LICENSE so GitHub's licensee and PyPI
  license classifier auto-detect the license. License terms unchanged
  (BSD-3-Clause-Clear; the NO EXPRESS OR IMPLIED LICENSES TO ANY PARTY'S PATENT RIGHTS clause distinguishes it from plain
  BSD-3-Clause).
• Fixed Hugging Face account handle typo Yuma-Ichikawsa →
  Yuma-Ichikawa in README, docs, data/*, and setup scripts
  (17 occurrences across 11 files).

Removed

• qqa.sa._qubo_glauber_sweep deprecated alias dropped — it
  forwarded to _qubo_seq_glauber_sweep and the buggy parallel-update
  semantics it warned about have been gone since 0.4.0.

Install

pip install qqa==0.6.0
pip install "qqa[gui]==0.6.0"

Upgrade notes

• Python 3.10+ (unchanged).
• No public API breakage: all user-facing entry points kept their
  signatures; only the private _qubo_glauber_sweep alias was removed.
• If you pin qqa>=0.5.1,<0.6, there is nothing on PyPI in that range;
  bump directly to qqa>=0.6.0.

Detailed changelog

See CHANGELOG.md
for the per-version breakdown of 0.5.1 / 0.5.2 / 0.5.3 / 0.6.0.

v0.5.0 — citation audit, broader classifiers, Codecov badge

First release with the OSS-promotion polish:

• Citation audit across the repo (src/qqa/__init__.py, both example
  notebooks): the QQA paper (Ichikawa & Arai, ICLR 2025) and the CPRA
  paper (Ichikawa & Iwashita, TMLR 2025) are now cited correctly and
  consistently. Adopted the TMLR-published title for CPRA.
• CITATION.cff preferred-citation block fixed (title and URL now
  match; arXiv:2409.02135 added as an explicit identifier).
• Broadened PyPI classifiers for better discoverability.
• Live Codecov coverage badge added to the README; Zenodo DOI badge
  placeholder ready to activate once this release mints the first DOI.

Full changelog: see CHANGELOG.md.

v0.4.0 — SA backend, GPU optimisations, automated PyPI publish

First release with a built-in Simulated Annealing baseline, GPU-friendly
optimisations to the QQA core loop, and automated PyPI publishing via
Trusted Publishing.

pip install qqa==0.4.0

Live demo: https://parallelquasiquantum4co.streamlit.app/
Docs: https://yuma-ichikawa.github.io/QQA4CO/

Added

• qqa.simulated_annealing: GPU-parallel SA baseline mirroring the
  qqa.anneal API. Auto-dispatches a QUBO fast path (Glauber-like
  parallel update, single matmul per sweep) or a generic single-spin
  Metropolis fallback. New SAResult dataclass.
• Streamlit dashboard: Compare page now has a PQQA vs SA shootout
  mode that races both backends on the same problem and reports a
  wall-clock speedup factor.
• CLI: qqa solve --backend sa with --sa-num-sweeps,
  --sa-beta-start, --sa-beta-end, --sa-schedule.
• anneal(..., mixed_precision="bf16") opt-in for bfloat16 autocast on
  CUDA (silently falls back to fp32 elsewhere).
• qqa.utils.enable_tf32() helper for Ampere+ matmul / cuDNN.
• train_cra_pi_gnn / train_cpra_pi_gnn: new
  early_stop_disc_patience argument.
• Head-to-head benchmark notebook:
  notebooks/benchmark_sa_vs_qqa_vs_pignn.ipynb.
• New docs/explanation/algorithm.md section covering SA.

Changed (performance)

• HistoryRecorder buffers per-epoch metrics as GPU scalars and does a
  single bulk .cpu() transfer in on_train_end, eliminating per-epoch
  host-device sync.
• qqa.anneal and the PI-GNN trainers now use
  optimizer.zero_grad(set_to_none=True).
• SpinRelaxation.project no longer allocates ones_like(x)
  intermediates.
• CategoricalRelaxation.penalty_from_forward removes a redundant
  forward pass per epoch.
• CPRA multi_problem: stacks same-shape Q_mat tensors and computes
  every replica cost in one batched einsum.

Net effect (CPU, 5-trial min, 32-node MIS):

Workload	Speedup
qqa.anneal (MIS)	+9%
qqa.anneal (Coloring)	+3%
CPRA single-problem	+3%
CPRA multi_problem (R=4)	+40%

QQA-MIS is bit-equivalent to 0.3.0; Coloring shows a <=0.12%
floating-point drift attributable to the penalty_from_forward
autograd graph change.

Compatibility

No public API removed. qqa.anneal, qqa.pignn.train_*, AnnealResult
and every problem class are unchanged. New keyword arguments
(mixed_precision, early_stop_disc_patience) are opt-in and default
to the prior behaviour.

Install / upgrade

pip install --upgrade qqa
pip install --upgrade "qqa[gui]"
pip install --upgrade "qqa[pignn]"

v0.3.0 — pip-installable OSS toolkit, spin problems, Streamlit GUI

First public OSS release of QQA4CO. Repackages the original research
prototype as a pip-installable PyTorch toolkit with a CLI, MkDocs site,
and a Streamlit dashboard.

pip install qqa==0.3.0

Live demo: https://parallelquasiquantum4co.streamlit.app/

Added

• Spin problem family in qqa.problems: Ising1D, EdwardsAnderson,
  SherringtonKirkpatrick, BinaryPerceptron, HopfieldMemory. New
  SpinRelaxation mapping [0, 1] -> +/-1 with differentiable forward.
• Visualization (qqa.visualization) with dual matplotlib / plotly
  backend: plot_best_trajectory, plot_schedule,
  plot_run_comparison, plot_parallel_coordinates,
  plot_solution_heatmap.
• CLI (qqa entry point): qqa version, qqa solve, qqa bench,
  qqa gui.
• Streamlit dashboard: problem definition -> live annealing ->
  visualization -> comparison.
• Example notebooks: MIS, Coloring, MaxCut, 3D Edwards-Anderson, SK,
  binary perceptron, Hopfield memory, parallel benchmark.
• MkDocs + Material docs site with auto API reference.
• Tooling: GitHub Actions CI, pre-commit, CONTRIBUTING.md,
  CITATION.cff.

Changed

• qqa.problems is now a subpackage (qubo.py, categorical.py,
  spin.py). Public symbols (MaximumIndependentSet, Coloring, ...)
  are preserved via re-export, so existing code keeps working.

Install

pip install qqa==0.3.0
pip install "qqa[gui]==0.3.0"