Refactor QQA into a pip-installable OSS toolkit (v0.3.0)

Restructure into a `qqa` package with unified `anneal()` API, a full
suite of spin-glass problems (Ising, Edwards-Anderson, SK, binary
perceptron, Hopfield), a `UserProblem` plug-in for custom losses, a
`qqa` CLI, a Streamlit dashboard with a live parallel-search view, and
an MkDocs site. Includes deep correctness tests and AppTest-driven
GUI checks.

Author: Yuma-Ichikawa

.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install package with all extras (CPU torch)
+        env:
+          PIP_EXTRA_INDEX_URL: https://download.pytorch.org/whl/cpu
+        run: uv sync --extra plotly --extra gui --extra docs --extra dev
+
+      - name: Ruff lint
+        run: uv run ruff check src tests scripts app
+
+      - name: Ruff format check
+        run: uv run ruff format --check src tests scripts app
+
+      - name: Run tests
+        run: uv run pytest -q

.gitignore

@@ -0,0 +1,43 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+
+# uv / virtualenv
+.venv/
+venv/
+env/
+
+# Testing / coverage
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Jupyter
+.ipynb_checkpoints/
+
+# OS
+.DS_Store
+
+# IDE
+.vscode/
+.idea/
+
+# MkDocs
+site/
+
+# Local task planning (not versioned)
+tasks/
+
+# Streamlit cache
+.streamlit/secrets.toml
+

.pre-commit-config.yaml

@@ -0,0 +1,16 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+        args: ["--maxkb=1024"]
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.9
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

.python-version

@@ -0,0 +1 @@
+3.10

CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based
+on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project
+follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.3.0] - Unreleased
+
+### Added
+
+- **Spin problem family** in `qqa.problems`:
+  - `Ising1D`, `EdwardsAnderson`, `SherringtonKirkpatrick`
+  - `BinaryPerceptron` (teacher-student), `HopfieldMemory`
+  - New `SpinRelaxation` that maps `[0,1]` → `±1` with differentiable forward.
+- **Visualization** (`qqa.visualization`):
+  - Dual backend (`"matplotlib"` default, `"plotly"` optional).
+  - `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 GUI** (`qqa gui` / `uv run streamlit run app/streamlit_app.py`):
+  problem definition → live annealing → visualization → comparison.
+- **Example notebooks**: MIS, coloring, MaxCut, 3D Edwards–Anderson, SK,
+  binary perceptron, Hopfield memory, parallel benchmark.
+- **Docs site** via MkDocs + Material 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.
+
+### Deprecated
+
+- `qqa.legacy.*` wrappers still work and emit `DeprecationWarning`; use
+  `qqa.anneal` instead.
+
+## [0.2.0]
+
+- Initial unified `qqa.anneal` API, package reorganization under `src/qqa`,
+  `uv`/`pyproject.toml` based install, smoke tests and demo scripts.
+
+## [0.1.0]
+
+- Original research release accompanying the ICLR 2025 paper.

CITATION.cff

@@ -0,0 +1,23 @@
+cff-version: 1.2.0
+message: "If you use QQA in your research, please cite the paper below."
+title: "QQA: Quasi-Quantum Annealing for Combinatorial Optimization"
+authors:
+  - family-names: Ichikawa
+    given-names: Yuma
+  - family-names: Arai
+    given-names: Yamato
+repository-code: "https://github.com/Yuma-Ichikawa/QQA4CO"
+license: BSD-3-Clause
+version: 0.3.0
+preferred-citation:
+  type: conference-paper
+  title: "Continuous Tensor Relaxation for Finding Diverse Solutions in Combinatorial Optimization"
+  authors:
+    - family-names: Ichikawa
+      given-names: Yuma
+    - family-names: Arai
+      given-names: Yamato
+  conference:
+    name: "International Conference on Learning Representations (ICLR)"
+  year: 2025
+  url: "https://openreview.net/forum?id=9EfBeXaXf0"

CONTRIBUTING.md

@@ -0,0 +1,63 @@
+# Contributing to QQA
+
+Thanks for your interest in improving QQA. This project aims to be a friendly,
+reproducible research tool for gradient-based annealing on discrete problems.
+
+## Setup
+
+We recommend [uv](https://github.com/astral-sh/uv) for dependency management.
+
+```bash
+git clone https://github.com/Yuma-Ichikawa/QQA4CO.git
+cd QQA4CO
+uv sync --extra plotly --extra gui --extra docs --extra dev
+uv run pre-commit install
+```
+
+This installs:
+
+- Core runtime (PyTorch, NumPy, NetworkX, SciPy, Matplotlib, tqdm)
+- Optional: Plotly (interactive viz), Streamlit (GUI), MkDocs (docs)
+- Dev tools: pytest, ruff, pre-commit, nbval
+
+## Running tests
+
+```bash
+uv run pytest -q
+```
+
+Tests are designed to finish in under a minute on CPU.
+
+## Code style
+
+- Ruff handles linting and formatting.
+- Target Python 3.10+.
+- Public functions should have a docstring (one-line summary + args/returns).
+
+```bash
+uv run ruff check src tests scripts app
+uv run ruff format src tests scripts app
+```
+
+## Adding a new problem
+
+1. Add a class to the appropriate file under `src/qqa/problems/`.
+2. Attach a `.relaxation` (Binary / Categorical / Spin) so `qqa.anneal()` can
+   dispatch.
+3. Export it from `src/qqa/problems/__init__.py` and `src/qqa/__init__.py`.
+4. Add a smoke test in `tests/` that solves a small instance and checks the
+   objective.
+
+## Submitting a PR
+
+- Ensure `ruff check`, `ruff format --check`, and `pytest` all pass locally.
+- Describe what you changed and why in the PR body.
+- Link to any relevant issues or papers.
+
+## Reporting issues
+
+Please include:
+
+- `qqa.__version__` and PyTorch version
+- A minimal reproducing snippet
+- Expected vs. observed behavior