Repo completion — v0.2.0 hardening, program README sync, design cleanup

[rosspeili]

Context

Individual feature issues (#1–#16) can merge incrementally. This wrap-up issue tracks everything needed to call spintronic-qrc code-complete at the same bar as spinq-vqe v0.1.2:

• All 6 notebooks executed with committed outputs
• benchmarks/ scripts runnable
• Tests green on default [dev] and optional extras documented
• pyproject.toml version bump
• Program-level Spintronics/README.md status updated from Not started to complete/in-progress with validated result
• Stale docs removed (scaffold language, wrong docstring DOIs)

User owns git tags and GitHub releases — do not create tags in this issue.

Goal

Single consolidation PR that brings the repo to v0.2.0 (or agreed version) with no loose ends.

Checklist

Code and tests

• pytest spintronic-qrc/tests/ -v — all pass on [dev]
• Document optional test commands:
  pip install -e "./spintronic-qrc[open,dev]" && pytest ...
  pip install -e "./spintronic-qrc[crossval,dev]" && pytest ...
• ruff check src/ tests/ — clean or documented ignores
• init.py all exports match public API in docs/api.md
• Fix stale docstring DOIs (e.g. reservoir.py still cites wrong Dambre IEEE TNN — use Sci. Rep. 10.1038/srep00514)

Notebooks and outputs

• All 6 notebooks in notebooks/ execute top-to-bottom
• figures/*.png committed (6 minimum from notebook plan)
• data/*.csv committed from notebooks + benchmarks/

Benchmarks

• python benchmarks/run_all.py --quick passes in CI-smoke time
• Full benchmark run documented in benchmarks/README.md with expected runtime

Documentation

• OVERVIEW.md matches Issue OVERVIEW validated results tables + paper LaTeX draft (repo publication package) #16 results (or merge OVERVIEW validated results tables + paper LaTeX draft (repo publication package) #16 before this)
• README.md notebook table matches actual files
• CHANGELOG.md — new section [0.2.0] - YYYY-MM-DD with Added/Changed summary
• pyproject.toml version = 0.2.0
• CITATION.cff version-field updated to 0.2.0
• Classifier Development Status -> 3 - Alpha or 4 - Beta if appropriate

Program integration

Update Spintronics/README.md (parent program repo) sections:

Section	Change
Section 10 repo table	spintronic-qrc: Not started -> Complete (v0.2.0) or In progress with NARMA baseline
Section 12 execution order	Repo 2 status updated
spintronic-qbench activation	NARMA-10 QRC baseline: mark done if Issue #4 shipped

Add one-line validated result (e.g. NARMA-10 test_nmse QRC vs ESN) in Repo 2 subsection.

Only edit parent README if this issue explicitly includes program repo — assignee confirms scope.

GitHub repo card (manual, document in PR)

Reminder for maintainer (not automated):

• Description, topics, website already suggested in prior session
• Create release v0.2.0 when ready (user action)

Acceptance criteria

• Version 0.2.0 in pyproject.toml and CITATION.cff
• CHANGELOG [0.2.0] entry complete
• Full pytest [dev] green
• run_all.py --quick green
• No .gitkeep-only directories that should have content (notebooks/, benchmarks/, data/, figures/)
• OVERVIEW deliverables all checked except paper if still draft
• Parent Spintronics/README.md updated OR separate follow-up issue linked

Files likely touched

• pyproject.toml
• CITATION.cff
• CHANGELOG.md
• OVERVIEW.md (final pass)
• README.md
• docs/testing.md
• Spintronics/README.md (parent, if in scope)
• Various docstring DOI fixes

Depends on

• Issues Implement end-to-end QRC pipeline (ApproxTimeEvolution + feature matrix builder) #1–Notebook 05 — Spintronic gate set, depth benchmarks, and Weyl chamber figure #13 — required minimum for code-complete B3+C1
• Issue Reproducible benchmarks/ scripts + committed benchmark outputs #10 — benchmarks
• Issue OVERVIEW validated results tables + paper LaTeX draft (repo publication package) #16 — paper/OVERVIEW (can merge in parallel; reconcile before tag)
• Issues Open-system QRC via QuTiP + Notebook 06 (Gilbert damping) #14–Qiskit Aer cross-validation of spin-chain unitary dynamics #15 — optional for v0.2.0; can defer to v0.2.1 with CHANGELOG note

Blocks

• Program Repo 3 (mtj-quantum-noise) start with QRC baseline confirmed
• spintronic-qbench QRC task ingestion
• Public v0.2.0 GitHub release (user-owned)

[rosspeili]

Amendment — spinq-vqe parity and hygiene

Add these items to the consolidation checklist (spinq-vqe v0.1.2 bar):

README Key results (mirror spinq-vqe)

spinq-vqe README has inline results tables and figure embeds. After Issues #4–#8 and #10 land, add to spintronic-qrc README.md:

• NARMA-10 table: QRC vs ESN test_nmse (from data/narma10_results.csv)
• Mackey-Glass one-line result (from data/mackey_glass_results.csv)
• Memory capacity headline: total_mc QRC vs ESN (from data/memory_capacity.csv)
• Gate depth one row at n_sites=8 (from data/gate_depth.csv) if Gate depth benchmarks — spintronic native set vs universal RZ + CNOT #12–Notebook 05 — Spintronic gate set, depth benchmarks, and Weyl chamber figure #13 done
• Embedded images: figures/qrc_narma10.png, optionally figures/memory_capacity.png

Keep OVERVIEW.md as the long-form narrative; README gets the at-a-glance numbers like spinq-vqe.

Repo hygiene

• Add .gitattributes (match spinq-vqe: *.py/*.md/*.csv LF, *.png binary)
• Fix stale docstring DOIs:
  - reservoir.py Dambre cite → Sci. Rep. 10.1038/srep00514 (not IEEE TNN)
  - readout.py same if applicable
  - Align module docstrings with REFERENCES.md
• tests/__init__.py if spinq-vqe parity desired (optional)
• Notebook links in README table: clickable paths like spinq-vqe ([02_qrc_narma10.ipynb](notebooks/...))

Program README (parent repo)

If in scope for this PR:

• Spintronics/README.md §10 and §12: spintronic-qrc status Not started → Complete (v0.2.0) with one NARMA-10 headline metric
• spintronic-qbench activation line: NARMA-10 QRC baseline ✅ when Notebook 02 — NARMA-10 end-to-end QRC + committed results #4 shipped

If parent README is out of scope, link a follow-up task in the PR description.

Out of scope (do not block v0.2.0)

• GitHub Actions CI (spinq-vqe has none)
• Updating spinq-vqe README back-link (separate small PR on Repo 1 after NARMA numbers exist)
• Zenodo DOI / git tags (maintainer-owned)

[rosspeili]

Public OVERVIEW pass (match spinq-vqe)

Rewrite OVERVIEW.md to spinq-vqe style:

• Remove cluster codes (B3, C1), "Workstream", internal deliverable checklist language
• Keep: motivation, methods summary, Key results tables, cross-repo diagram, references
• Move execution-order / planning notes to a short internal PLANNING.md (optional) or drop

Public entry points after this: README → docs/ → OVERVIEW (all visitor-safe).