qmlkit 0.1.0__tar.gz → 0.2.0__tar.gz

{qmlkit-0.1.0 → qmlkit-0.2.0}/.github/workflows/docs.yml

@@ -46,7 +46,12 @@ jobs:
 
   deploy:
     name: Publish to GitHub Pages
-    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    # A manual run has to be able to publish, or `workflow_dispatch` is a build
+    # button with no effect - which is exactly when it is reached for, because the
+    # push trigger did not fire.
+    if: >-
+      github.ref == 'refs/heads/main'
+      && (github.event_name == 'push' || github.event_name == 'workflow_dispatch')
     needs: build
     runs-on: ubuntu-latest
     permissions:

qmlkit-0.2.0/AGENTS.md

@@ -0,0 +1,144 @@
+# AGENTS.md
+
+Instructions for a coding agent working **on** qmlkit. To *use* the library, read
+[`docs/llms.txt`](docs/llms.txt) instead — it is the same information written for
+the caller rather than the contributor.
+
+[`HANDOFF.md`](HANDOFF.md) is the long version of this file: current status, why
+each convention exists, and what to do next. Read it before anything non-trivial.
+This page is the short list of things that will break the build if you get them
+wrong.
+
+## The map
+
+19,000 lines over 79 modules, 196 names in the top-level `__all__`. Two halves:
+
+```
+src/qmlkit/
+  core/          the IR, and only the IR: ir · builder · gates · observables · execute
+  core/backends/ seven of them. base.py supplies the semantics; a backend supplies
+                 statevector() and inherits sampling, grouping, expectation, batching
+  ansatz/  encoding/  gradients/  kernels/  nn/      the ML layer
+  algorithms/    VQE · ADAPT · QAOA · chemistry · autoencoder · clustering · rl
+  *.py           the honesty layer — diagnostics · baselines · budget · evaluate ·
+                 imbalance · provenance · search · progress · report · metrics
+  utils/errors.py  how every "unknown X" error in the library is built
+  _aliases.py      PennyLane and Qiskit names, answered with the qmlkit one
+```
+
+The top-level modules are the point of the project. `core/` is machinery in service
+of them.
+
+## Commands
+
+```bash
+pip install -e ".[dev,torch,qiskit,cirq,sklearn,pennylane]"
+pytest -q                                  # the whole suite
+pytest -q -m "not pennylane"               # faster, skips the parity cases
+ruff check src tests && ruff format --check src tests && mypy
+python scripts/generate_llms_txt.py        # after any docs or public-API change
+python -m mkdocs build --strict            # after any docs change; CI runs it
+python scripts/verify_install.py           # the core really does import with only NumPy
+QMLKIT_TORTURE_EXAMPLES=1500 pytest tests/test_torture.py   # ~10 min, before a release
+```
+
+SpinQit needs its own interpreter — it ships wheels for Python 3.8–3.10 only and
+pins `numpy<2`:
+
+```bash
+C:/Users/pc/miniconda3/envs/spinq_env/python.exe -m pytest -m spinqit
+```
+
+## Rules the tests enforce
+
+1. **An algorithm owns its loop, not its circuit.** Every model takes `ansatz=` /
+   `feature_map=` / `filter=` and must actually use it. `tests/test_injection.py`
+   injects two different sizes and asserts the parameter count follows.
+2. **Estimators must be scikit-learn clonable.** Constructor arguments stored under
+   their own names, plus `SklearnCompatible`. This keeps scikit-learn optional while
+   letting QSVC/QSVR run inside `Pipeline` and `GridSearchCV`.
+3. **The core depends on NumPy and nothing else.** Not SciPy — use `math.erf` and the
+   stdlib. CI installs nothing else in the `core` jobs, and this has been broken once.
+4. **Documentation is executable.** `tests/test_docs.py` runs every Python block on
+   every page, so an API change and its docs go in the same commit.
+5. **Names have to stay findable.** `qmlkit/_aliases.py` maps what PennyLane and
+   Qiskit call each thing; `tests/test_agent_api.py` asserts every target still
+   exists. Rename a public name and you update that table in the same commit.
+6. **`docs/llms.txt` is generated and committed.** Change the docs or the public API
+   and regenerate it, or CI fails on the stale copy.
+
+## Traps that have already cost time
+
+- **Never use a NumPy-2-only API** (`np.trapezoid`, `np.in1d`, …) in `src/` or
+  `tests/`. SpinQit pins `numpy<2` and the suite must pass in both environments.
+- **Always write `npt.NDArray[Any]`, never bare `np.ndarray`.** Type-parameter
+  defaults only arrived in NumPy 2.3, so 3.10 CI fails with 60 `type-arg` errors.
+- **Never set `python_version` in `[tool.mypy]`.** It makes mypy parse dependency
+  stubs at that version too, and NumPy's stubs use PEP 695 `type` statements, which
+  are a syntax error before 3.12. Cross-version signal comes from CI running mypy
+  on 3.10.
+- **The PennyLane parity fuzzer draws gate names from a snapshot taken at import**,
+  not from the live registry — other test modules register throwaway gates at run
+  time, which made it pass alone and fail in a full run.
+- **Extend `tests/test_pennylane_parity.py` when adding a gate.** A test there
+  asserts the mapping covers every built-in gate, so a new one cannot escape
+  cross-validation. Every bug found in this project has been the
+  plausible-wrong-number kind that only a second implementation catches.
+
+## Where a change has to land
+
+The library is built on registries, so adding something is usually one call — and
+then three or four places that will not fail loudly if you forget them.
+
+| Adding | Also touch |
+|---|---|
+| **A gate** | `frequencies` on the `GateDef` or differentiation is refused; `dmatrix` or adjoint is refused; the PennyLane mapping in `tests/test_pennylane_parity.py`, which asserts it covers every built-in gate |
+| **An ansatz or conv filter** | `register_*`, and check it is not inert — an all-`rz` filter does nothing at all from `|0…0⟩`, which is why `test_no_shipped_filter_is_inert` exists |
+| **A backend** | `supports_exact` and `supports_statevector` are a contract, not metadata. Then **sweep the public API against it**: adding the noisy backends broke `diagnose`, `expressibility`, `entangling_capability`, `fidelity_samples`, `metric_tensor` and `qng_step`, and the suite did not notice |
+| **A diagnostic finding** | Write the test so it asserts the finding is **true**, not that it fired. The old tests asserted firing, which is how three wrong findings survived. A false positive here is worse than a false negative: it teaches people to ignore the tool |
+| **Anything public** | `docs/llms.txt` regenerated, a reference page entry, and a CHANGELOG entry |
+| **A version bump** | `pyproject.toml` **and** `src/qmlkit/__init__.py`. A third hardcoded copy in `scripts/verify_install.py` once failed the release gate |
+
+**Releasing is a tag on this repository**, which `release.yml` turns into a TestPyPI
+then PyPI publish over Trusted Publishing - no token is handled anywhere. It asserts
+the tag matches `pyproject.toml` before it builds. A PyPI version number can never be
+reused, so tags stay unpushed until the release is actually wanted, and a release that
+half-completes burns the number. `RELEASING.md` has the procedure.
+
+Until 2026-09-13 this repo was a `git subtree split` of a subdirectory in the lecture
+repository. If you find a document that still says so, it is stale - fix it.
+
+## Writing
+
+The prose is a deliberate artefact. Match it rather than inventing a second voice.
+
+- **Claims enter through the failure they prevent**, never through the feature name.
+  The order is: here is a way to be wrong, here is why it does not raise, here is the
+  call. Almost nothing opens with "qmlkit provides".
+- **Every number carries its provenance.** "Measured on a 5-qubit hardware-efficient
+  ansatz"; "measured: five frequencies". A bare number reads as an unsupported claim.
+- **Caveats get their own sentence, in the same voice as the claims**, usually last and
+  usually against the author's interest — "JAX is not installed on the benchmark
+  machine, so jit-compiled PennyLane is untested and unclaimed."
+- **Headings are assertions, not labels**: "Data re-uploading is a pattern, not a
+  structure"; "Noise, when you ask for it by name". Label headings mark reference
+  sections, and the contrast is the point.
+- A long sentence that does the analysis, then a short one that lands it. British
+  spelling. Second person about the reader's actions, never their level.
+
+## Design commitments
+
+- **Simulator-only for the whole 0.x line.** This is a constraint that propagates,
+  not a scope trim: it makes `adjoint` the correct default gradient, makes shot
+  noise opt-in, and demotes anything whose value is cutting *measurement* cost.
+  Parameter-shift stays the teaching subject and the reference that validates
+  adjoint — never the performance default.
+- **Simple on top, open underneath.** Three layers, and nothing at a higher one
+  hides a lower one. Every extension point is a registry.
+- **When something is named after a pattern rather than a structure, make it a
+  composition, not a class.** Data re-uploading is `EncodingLayer` in the block
+  vocabulary, with `reupload()` as a convenience over it.
+- **The error message is the documentation.** Most callers are models that will not
+  read the docs site; they read the traceback. An error about a name says what was
+  wrong, what was probably meant, and what is allowed — build it with
+  `qmlkit.utils.errors.unknown`.

{qmlkit-0.1.0 → qmlkit-0.2.0}/CHANGELOG.md

@@ -4,6 +4,447 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project uses
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2026-09-13
+
+**Upgrading from 0.1.0? This release contains eleven correctness fixes as well as the
+features below, and four of those defects corrupt a result silently.** They were
+prepared as 0.1.1, which was never published — everything in that section further down
+ships here. The worst of them is in the torch backend, which computed a *different
+circuit* from every other backend, so `backend="torch"` and `method="backprop"` returned
+wrong numbers and nothing raised. If you are on 0.1.0, upgrade.
+
+### Fixed - a documented optimiser that never ran
+
+`OPTIMIZERS` has four entries and two of them need the gradient injected by the caller,
+but every injection site named `gradient-descent` alone. `optimizer="adam"` therefore
+raised `TypeError: _adam() missing 1 required keyword-only argument: 'grad'` from `VQE`,
+`QAOA` and `AdaptVQE` alike — one of the four documented optimiser names could not be
+used from any of the three algorithms that list it.
+
+`tests/test_optimizer_wiring.py` now parametrises over `OPTIMIZERS` itself rather than a
+hand-written list, so a fifth entry cannot be added without being covered, and one test
+drives both gradient routes to the known ground state — an injected gradient that was
+*wrong* would pass a wiring test and fail that one.
+
+Also fixed: two docstrings whose LaTeX had been eaten by a shell heredoc (`\rho` and
+`\rangle` became line breaks, `\theta` became a tab), and three references to things
+that do not exist — `kernel.matrix(X)` in a user-facing error message where the call is
+`kernel(X)`, `qk.datasets.moons` in a live doctest where it is `make_moons`, and an
+"AmplitudeEncoder feature map" in the PennyLane alias table.
+
+### Added - you can watch a run instead of waiting for it
+
+`qk.plan` says what a run will cost before it starts and `qk.diagnose` says what went
+wrong after it finishes. In between there was nothing, and in between is where the
+hours go — a quantum kernel on a few hundred points is tens of thousands of circuits
+behind a single silent call that returns when it returns. "How much is left" is one
+of the most common questions asked about every library in this field, and none of
+them answers it.
+
+```python
+with qk.progress() as run:
+    gram = kernel(X)
+    model.fit(X, y)
+```
+
+```text
+kernel gram  3,412/12,720   27%   14.2s elapsed  ~37s left
+```
+
+and afterwards, where the time actually went:
+
+```text
+>>> print(run.report())
+Run finished in 51.4s
+kernel gram               12,720 items    47.9s    3.77 ms/item
+fit VQC                      600 items     3.2s    5.33 ms/item
+  (untracked)                              0.3s   - setup, data handling, and anything outside a task
+```
+
+Three properties it holds to, in priority order, each with a test:
+
+1. **It does not change any number.** A seeded kernel and a seeded circuit produce
+   bit-identical results watched and unwatched. A reporter that perturbed a result
+   would be a worse defect than the silence it replaces.
+2. **It is free when nobody is watching.** With no active reporter, the tracking
+   calls inside the library cost one comparison against `None`, and the live line
+   redraws at most ten times a second however fast the loop runs.
+3. **It does not claim to know what it does not.** An estimate from four items in
+   half a second says more about scheduling noise than about the run, so it prints
+   `estimating` until there is evidence — the same rule the rest of the library
+   follows about reporting a measurement.
+
+Wired into the two loops that actually take the time: the pair-at-a-time kernel Gram
+(sampled kernels, non-inversion estimators, and any backend without a statevector)
+and `HybridModel.fit`, which covers `VQC` and `VQRegressor`. `qk.track` wraps any
+iterable, and `qmlkit.progress.task` is what library code calls — it returns a silent
+stand-in when nothing is watching, so no loop needs to branch on it.
+
+Nothing is printed unless `qk.progress()` is entered, and the live line goes to
+stderr so piping a script's stdout to a file does not collect redraws.
+
+### Added - the run writes itself up
+
+A run produces a number, and a month later the number is all that is left. A run now
+also records its *trajectory* — `run.log(name, value, step)` — and can write the whole
+thing out as one HTML file:
+
+```python
+with qk.progress() as run:
+    run.note(dataset="breast-cancer", seed=0)
+    model.fit(X, y)
+
+run.save_html("run.html")
+```
+
+`HybridModel.fit` logs three series per epoch, so `VQC` and `VQRegressor` get this
+without asking: **loss**, **gradient norm** and **parameter norm**. The second is
+there because loss alone cannot tell a solved problem from a plateau, and the third
+because weights running away looks like nothing at all in a loss curve. Computing
+them costs a pass over the parameters, so it happens only when something is watching.
+
+The page is deliberately a *file*, not a server. A dashboard you have to start,
+connect to and keep alive is a dependency, a port and a process; a page you can open,
+email, and drop next to the result in a directory is none of those and outlives all
+of them. The charts are inline SVG for the same reason: nothing to fetch, nothing to
+pin, nothing to break in two years. Tests assert it — no `<script>`, no `src=`, no
+`http`, and every label and metadata value escaped, because a report is exactly the
+kind of artefact that gets passed around.
+
+Both chart edge cases are handled and tested because both are real runs: a single
+point has no range to scale against, and a flat series has zero range — which is the
+loss curve of a model that never learned, the run you most want to look at. That one
+is labelled `flat — never moved` rather than drawn as a misleading straight line at
+an arbitrary height.
+
+### Added - `diagnose` can now be asked whether the quantum layer earned its place
+
+`qk.diagnose(model, X, y)` takes a *trained* model and the data it was trained on,
+and answers the question the structural checks cannot: not "is this architecture
+broken" before the run, but "it trained, it converged, and it works just as well
+without the quantum part". That complaint is the most common one in the field and
+nothing in any library answers it.
+
+The new finding is `QUANTUM_LAYER_BYPASSED`. A forward hook captures what the
+quantum layer received and what it returned; the same hyperparameter-free probe
+scores both, averaged over five splits. The finding fires only when separability
+measurably *dropped* across the layer by more than the spread across those splits —
+the same verdict rule `qk.baseline` uses, where a lead inside the spread is not a
+lead. It reports both numbers, so the claim can be argued with:
+
+```text
+[warning] QUANTUM_LAYER_BYPASSED: The quantum layer reduced separability: the same
+probe scores 0.951 on what the layer received and 0.578 on what it returned, a drop
+of 0.373 against a spread of 0.028 across 5 splits. The classical layers around it
+are carrying this model.
+```
+
+The probe is `NearestCentroid` precisely because it has no solver and no
+hyperparameter: neither side of the comparison can win by having been tuned better,
+so a difference in score is a difference in the activations. Classification targets
+only — a continuous target is declined rather than guessed at. Without `X` and `y`,
+or without torch, `diagnose` behaves exactly as before.
+
+`X` and `y` are optional positional parameters, so every existing call is unchanged.
+
+## [0.1.1] - prepared, never published
+
+This version was cut, verified and then superseded before it was tagged: the tree
+gained features while it sat, so the correctness work below shipped in **0.2.0**
+instead. There is no `0.1.1` on PyPI and there never will be. The section is kept in
+full because it is the account of eleven defects that were in 0.1.0, and a reader
+upgrading from 0.1.0 needs it.
+
+**Upgrade from 0.1.0.** Everything below was found after 0.1.0 was published, so it is
+all still present in the version on PyPI. One defect was reported by a reader using the
+library; ten came from an adversarial audit told to find a case where qmlkit returns a
+*wrong number* rather than an error. Four of the ten corrupt a result silently, and the
+worst of those is in the torch backend, which computed a different circuit from every
+other backend - so `backend="torch"` and `method="backprop"` returned wrong numbers,
+reachable from the built-in `conv_block(filter="su4")`. Nothing raised in any of the
+four.
+
+The audit's account is split over three sections below by where each defect lived:
+*three silent wrong numbers*, *five defects*, and the diagnostic in *a diagnostic that
+asserted what it had only inferred*. They are one audit, settled against one dense
+reference simulator that shares no code with qmlkit.
+
+### Fixed - a composition the README recommended built the wrong circuit
+
+Reported by a reader who tried the two-feature-map example and read the parameter
+indices off the built circuit.
+
+**Two feature maps in one model shared each other's angles.** `EncodingLayer`
+reserved circuit input slots per *angle* rather than per feature map, always taking
+slots `0..n_angles-1`. So in the composition the README advertised verbatim -
+
+```python
+# docs: skip - this is the defect, kept as it was written
+qk.Ansatz(2, qk.EncodingLayer(zz) + qk.RotationLayer("ry") + qk.EncodingLayer(angle),
+          n_inputs=3)
+```
+
+— the `ZZFeatureMap` took slots 0, 1, 2, the rotation layer took 3, 4, and the second
+encoding took **0 and 1 again**. Those slots already held the ZZ map's *transformed*
+angles: `ZZFeatureMap(2).angles([0.3, 0.7])` is `[0.6, 1.4, 13.876]`, because a Z term
+follows the `Rz(2 phi)` convention. The trailing `Ry` therefore encoded `2*x_i` where
+the caller asked for `x_i`. Nothing raised. The circuit built, bound, differentiated,
+trained and converged - on the wrong numbers. That is the failure class this library
+exists to refuse, in an example of its own.
+
+Each feature map now owns a **disjoint** range of input slots, allocated in the order
+the maps first appear; the *same* map re-used keeps the range it already has, which is
+what makes re-uploading feed the same data in again rather than consume new features.
+`Ansatz.angles` concatenates the maps' angles in slot order and `Ansatz.angle_jacobian`
+stacks their Jacobians, so `bind(x, weights)` and the chain rule down to the data both
+follow. A composed model now also satisfies the `Combined` protocol, so it can go
+straight into a `QuantumLayer` - which the README promised and which had never worked.
+
+Slots could not instead be keyed by *feature*, so that both maps read the raw `x`:
+a slot is referenced by a `ParamRef`, which is affine in one parameter
+(`scale * theta[i] + offset`), and a Pauli map's higher-order angle is
+`2 * prod_j (pi - x_j)` - nonlinear, in several features at once. The map from features
+to angles has to stay classical, which is what `angle_jacobian` is for.
+
+**The error message steered users into the bug.** With `n_inputs=2` the same
+composition raised *"the circuit reserves 2 input slots but this feature map needs 3"*,
+which tells you to raise `n_inputs` - and raising it to 3 is exactly what produced the
+silent collision. `n_inputs` is now **inferred** from the block, so there is no count
+to get wrong; passing one that disagrees with what the encodings reserve raises and
+names the sum. This closes the last hand-counted number in `Ansatz`, whose docstring
+already promised that parameter counts are "inferred from a dry build, never
+hand-counted, so a miscount is not a failure mode".
+
+**The README example is fixed, and now runs.** `tests/test_docs.py` executes every
+Python block in `docs/`, but never reached `README.md` - the most-read page was the
+one page not under the executable-documentation rule, which is why this survived. The
+README is a reference rather than a tutorial and most of its blocks are deliberate
+fragments naming an API, so it opts *in*: a self-contained block marked `# docs: run`
+is executed by `test_readme_blocks_marked_runnable_do_run`.
+
+### Fixed - observable arithmetic that QML cost functions need
+
+`I - Z` and its relatives are how a projector is written, and most of the ways to
+write one did not work. `Z(0) + Z(1)` and `2.0 * Z(0)` did; these did not:
+
+| Expression | Was |
+|---|---|
+| `sum([Z(0), Z(1)])` | `TypeError` - no `__radd__` for `sum`'s `0` start value |
+| `Z(0) + 1` | `AttributeError: 'int' object has no attribute 'terms'` |
+| `1 - Z(0)`, `Z(0) - Z(1)`, `I() - Z(0)` | `TypeError` - no `__sub__` or `__rsub__` |
+| `-(Z(0) + Z(1))` | `TypeError` - `PauliSum` had no `__neg__` |
+| `Z(0) / 2` | `TypeError` - no `__truediv__` |
+
+`PauliString` and `PauliSum` now implement `__add__`/`__radd__`, `__sub__`/`__rsub__`,
+`__neg__` and `__truediv__`. A scalar promotes to that multiple of the identity, and
+the additive identity is dropped rather than carried as `0*I`, which is what lets
+`sum(...)` return the sum itself. Numbers are recognised through `numbers.Complex`, so
+NumPy scalars work - `np.int64` is not an `int` subclass. An operand with no sensible
+reading returns `NotImplemented`, so `Z(0) + "x"` reports unsupported operand types
+instead of failing somewhere inside qmlkit.
+
+### Fixed - five defects found by an adversarial audit
+
+An agent was asked to break qmlkit 0.1.0 through its public API, and to settle every
+disagreement against a dense simulator it wrote itself - one that reads `spec.ops` and
+never calls qmlkit's own execution code. Most of the library held: all 20 gate
+matrices column by column, four exact gradient routes against an analytic product
+rule, every metric against scikit-learn, the noisy backends against their closed form
+to 1e-16. What it found was the other kind of defect - the one where a plausible
+number comes back and nothing raises. Five of those were in the kernel, analysis and
+metric layers.
+
+**`QuantumKernel(estimator="hadamard")` returned `Re(<x'|x>)^2` instead of
+`|<x'|x>|^2`.** The wrapper squared `hadamard_test`, whose `part` defaults to
+`"real"`, so wherever a feature map produced a complex overlap the estimator dropped
+the imaginary component. Worst observed error 0.831, on a quantity bounded by 1. The
+three estimators are documented as agreeing on a simulator; two of them did.
+
+Nothing downstream could catch it. Squaring the real part alone leaves a Gram matrix
+that is still symmetric, still positive semi-definite and still unit-diagonal -
+`K(x, x)` is real for every feature map, so the diagonal is 1 either way - and
+`diagnose` therefore reported nothing. A `QSVC` fitted on the wrong kernel scored
+*higher* than one fitted on the right one. A Hadamard test measures one *component*
+of a complex overlap, so the modulus takes two circuits: the estimator now runs both
+and returns `Re^2 + Im^2`, and `n_evaluations` reports 2 per pair rather than 1,
+because a caller budgeting circuits is entitled to the real count.
+
+**`reduced_dm` silently ignored the order of `wires`.** It did
+`keep = sorted(set(wires))`, so `reduced_dm(psi, [1, 0])` returned the `[0, 1]`
+matrix. That result is still Hermitian, still has trace 1 and still has the right
+eigenvalues, so `purity`, `vn_entropy`, `mutual_info` and every other
+basis-independent reading built on it agreed with the truth - which is how a
+subsystem-ordering defect sits under a passing test suite indefinitely. `wires` is now
+honoured as given: qubit `wires[0]` is the returned matrix's most significant bit, and
+`[1, 0]` is `SWAP . rho . SWAP` rather than `rho`. `[0, 0]` used to de-duplicate itself
+into a 2x2 matrix and now raises, naming the repeated qubit. The PennyLane parity
+suite compares descending pairs against `qml.math.reduce_dm`, so a second
+implementation holds the convention in place.
+
+**`KERNEL_AT_CONCENTRATION_SCALE` fired on kernels that separate their classes
+perfectly, and its message contradicted its own numbers.** Two defects in six lines.
+The rule compared against `2 * kernel_spread(n)` while the message printed
+`kernel_spread(n)`, so it reported *"spread 5.00e-01 is at or below ... 2.50e-01"* - a
+sentence refuted by the two numbers inside it. And because off-diagonal kernel entries
+live in `[0, 1]`, their standard deviation cannot exceed 0.5, which is exactly the
+threshold at two qubits: below three qubits the check fired on **every** Gram matrix,
+including one built from mutually orthogonal points. `bool(qk.diagnose(K))` was
+therefore true for a good kernel - the same cry-wolf failure as `ENCODING_COMMUTES`
+above, and the one that teaches people to stop reading diagnostics at all. The message
+now quotes the threshold it actually used, and the check is skipped where that
+threshold exceeds what the statistic can attain, because a comparison nothing can pass
+is not a test.
+
+**`geometric_difference(K, K)` returned `sqrt(N)` rather than 1.** Huang et al.'s `g`
+is compared *against* `sqrt(N)`; that threshold had been folded into the statistic
+itself, which left a number agreeing with no published one and a self-comparison whose
+value depended on the sample count. It now returns
+`sqrt(||sqrt(K_Q) K_C^-1 sqrt(K_Q)||)`, which is 1 for identical kernels, and the
+docstring names `sqrt(N)` as the bar for the caller to apply. The kernel study and the
+credit-risk example both compared `g` against a hard-coded `10`; both now compare
+against `sqrt(N)`, which is the literature's test and the only one that scales with
+the data.
+
+**`evaluate.regression` reported `r2 = 0.0` for a perfect fit on a constant target.**
+R2 scores a model against the variance baseline - predict the mean everywhere - and a
+constant target has no variance, so the ratio is `0/0`. Reporting 0.0 made a perfect
+prediction indistinguishable from one wrong by a factor of 33: both scored zero, in
+the module whose premise is that a metric says when it is misleading. `r2` and
+`explained_variance` are now `nan` there, with a note naming the value every target
+takes and pointing at `mse` and `max_error`, which need no baseline. This is a
+deliberate departure from scikit-learn, which returns 1.0 for the perfect case and 0.0
+for the rest - a convention that cannot be read back, since a 0.0 could mean either
+"undefined" or "no better than the mean".
+
+### Fixed - three silent wrong numbers, found by attacking the library
+
+An agent was asked to break qmlkit: to find a case where it returns a *wrong number*
+rather than an error. Its ground truth was a dense simulator it wrote itself, which
+reads only `spec.ops`, builds every gate matrix by hand, and never calls qmlkit
+execution code. It found ten defects; these three were the ones that corrupt a result
+without saying anything.
+
+**The torch backend computed a different circuit.** `_apply_torch` reimplements
+`np.moveaxis` and drops the `sorted(zip(destination, source))` numpy does, so for a
+two-qubit gate on wires `(a, b)` with `a > b` the *untouched* wires came out permuted.
+`Z(3)` on a four-qubit circuit read `-0.1288` where NumPy, Qiskit and Cirq all agreed
+on `-0.7374`. `method="backprop"` differentiates through the same function, so its
+gradients were wrong too, and `qk.conv_block(filter="su4")` reaches it without anyone
+hand-writing a circuit. `qk.selfcheck` catches this and names the cause exactly -
+nothing was running it.
+
+**`expectation(..., return_std=True)` reported a fabricated error bar.** It fed any
+observable into the single-Pauli formula `sqrt((1 - z^2)/shots)`, which for a sum is
+too tight, too loose, or - once `|<O>|` reaches 1 - *exactly zero*. Every molecular
+Hamiltonian came back with `+-0.00000`, an error bar that looks converged and does not
+move with the shot count. It is now computed rather than approximated: inside a
+qubit-wise-commuting group every term is diagonal in the measured basis, so the
+group's variance follows from the probabilities the exact path already reads, and
+groups measured on independent shots add. Checked against the empirical spread of 400
+repeated samplings, it agrees within 2% for single terms, sums, weighted sums and
+two-basis observables alike.
+
+**`purity(state, backend=<mixed-state backend>)` returned a hard-coded 1.0**, on the
+premise that a statevector is pure by construction - true, and not what was asked when
+the caller named a density-matrix backend. It reported 1.0 for a state whose purity
+was 0.309.
+
+### Added - property-based torture tests
+
+`tests/test_torture.py`: thirteen invariants that hold *by mathematics* rather than by
+design, checked over randomly generated circuits with Hypothesis, which shrinks a
+failure to the smallest circuit that still shows it. `hypothesis` had been a dev
+dependency and was unused.
+
+The properties are deliberately not comparisons against stored values: a test that
+pins today's output catches a change, a test that pins an invariant catches a mistake,
+and only the second is worth running against random input. All exact gradient routes
+agree; every backend agrees with the reference; batched equals looped; a tied weight's
+gradient is the sum over its occurrences; adjoints undo, states normalise, expectation
+is linear in the observable and inside its spectrum; Qiskit and Cirq round trips
+reproduce statevectors; sampling lands inside its error bars. Depth is tunable with
+`QMLKIT_TORTURE_EXAMPLES` - cheap in CI, and a campaign at 1,500 examples per property
+(~19,500 circuits) passes clean.
+
+One caveat worth recording: the backend-agreement property originally skipped torch,
+on the reasoning that a differentiable simulator is a different kind of backend. That
+exclusion is exactly what let the permutation bug above survive. It no longer skips it,
+and the reason is written into the test.
+
+### Added - Adam, selective classification, and Study 8
+
+**`adam`** joins `rotosolve`, `spsa` and `gradient-descent`. Its absence was found
+the hard way: an agent reproducing a published method outside the torch bridge had to
+hand-roll one, and its first run put the paper's method *below* the baseline - its own
+diverging optimiser, not the method. A hand-rolled optimiser that diverges looks
+exactly like a technique that does not work. `qmlkit.optim.minimize_adam`, with
+`adam_step` and `AdamState` public for when the loop is yours; keep the state between
+steps or Adam quietly becomes gradient descent with a decaying learning rate.
+
+**`qk.evaluate.selective` and `qk.evaluate.risk_coverage`** score a classifier that is
+allowed to decline. Selective accuracy - accuracy on the samples the model chose to
+answer - rises monotonically as it abstains more, reaching 1.000 on the single sample
+it is surest about, so quoting it against a model that answered everything compares
+two different questions rather than two models. `selective` reports coverage beside it
+and makes the *comparable* number the primary one, so `scores.score` cannot quietly
+become the flattering one. `risk_coverage` gives the whole trade plus AURC, which
+abstaining more cannot inflate.
+
+**Study 8** measures it on a real model: a `VQC` scoring 0.8947 answering everything
+climbs to a selective **0.9479** at threshold 0.80 while its comparable accuracy
+*falls* to **0.7982**. Abstention made the reported number better and the model worse,
+and only one of the two columns says so.
+
+### Fixed - a diagnostic that asserted what it had only inferred
+
+**`ENCODING_COMMUTES` reported an error on correct architectures.** The check was
+structural: matching rotations implied a collapse. But `Ry(x) Ry(t) Ry(x) Ry(t)`
+merges *on one wire with nothing in between* - any entanglement breaks it, and the
+check could see neither an entangler in the trainable block nor an entangling feature
+map. Measured against the library's own `fourier.spectrum`, it claimed one frequency
+where the band was `0..4`. It now uses the structural test as a trigger and confirms
+with the spectrum before reporting. A false positive in the honesty layer is worse
+than a false negative: it teaches people to ignore the tool.
+
+The same blindness sat in `reupload()`'s construction-time warning, whose message had
+a second defect - it interpolated the `rotations` *parameter* rather than the gates
+actually found, so passing an explicit block produced "the trainable block only uses
+('rz','ry','rz') ... Use a non-commuting block such as ("rz","ry","rz")", recommending
+the thing it was complaining about.
+
+**`list_baselines()` repeated a name registered for both tasks.** The registry is
+keyed by task and name deliberately, so `rbf-kernel-ridge` serves classification and
+regression; the listing read the values and never deduplicated.
+
+**`Scores.get("precision")` returned `None`.** `__getitem__` already answered a wrong
+key with a did-you-mean and `.get` bypassed it, so a near-miss became a silent `None`
+that surfaced later as a `TypeError` from inside numpy. An explicit default is still
+honoured without comment.
+
+### Changed
+
+- `Ansatz(..., n_inputs=)` now defaults to `None`, meaning *infer*. Existing calls that
+  passed the correct total keep working; one that passed a different number now raises
+  rather than silently building a circuit whose encodings overlap.
+- `Ansatz` gained `feature_maps`, `angles`, `angle_jacobian` and `n_features`.
+  `ReuploadModel`'s own `angles`/`angle_jacobian` were identical for its single map and
+  are now inherited.
+- Composing feature maps that read different numbers of features now raises. Every map
+  in one model is handed the same `x`, so such a model could never have been bound.
+- `scripts/verify_install.py` compared `__version__` against a hardcoded `"0.1.0"` - a
+  third copy of the version that had to be bumped by hand, and the gate failed on this
+  release for that reason alone. It now reads the installed distribution metadata and
+  checks the module constant against it, which is what the check was named for.
+- `QuantumLayer` treats a model as carrying its own encoding only when it reserves
+  input slots. Every `Ansatz` can map data onto its slots now, so the four-attribute
+  check alone no longer distinguishes a model from a bare ansatz.
+- **`geometric_difference` now returns values `sqrt(N)` times smaller than 0.1.0's.**
+  Code that compared it against a hand-picked constant will read differently and
+  should compare against `sqrt(N)` instead, which is the comparison the statistic was
+  always for.
+- `QuantumKernel(estimator="hadamard").n_evaluations` counts two circuits per pair
+  rather than one, which is how many it now runs.
+
 ## [0.1.0] - 2026-09-12
 
 First release.