qmlkit 0.1.0__py3-none-any.whl

qmlkit/gradients/adjoint.py

@@ -0,0 +1,138 @@
+r"""Adjoint differentiation — exact gradients in one backward pass.
+
+Parameter-shift needs ``2P`` circuit evaluations because a real device can only be
+*run*, never inspected. On a simulator the state is right there, so the whole
+gradient comes out of a single forward and a single backward sweep — independent
+of ``P``.
+
+The sweep. With :math:`|\psi_j\rangle = U_j \cdots U_1 |0\rangle` and
+:math:`E = \langle\psi_n| O |\psi_n\rangle`,
+
+.. math::  \frac{\partial E}{\partial\theta_k}
+           = 2\,\mathrm{Re}\,\langle\lambda_k|\,\partial_k U_k\,|\psi_{k-1}\rangle,
+           \qquad \lambda_k = (U_n\cdots U_{k+1})^\dagger O |\psi_n\rangle
+
+so walking backwards and undoing one gate at a time keeps both states current at
+``O(1)`` extra memory.
+
+This is exact — the gate derivatives are closed-form, not finite differences — but
+it is **simulator-only**, because no device will hand you an amplitude. Since
+``0.x`` is simulator-only anyway, it is the right default for training;
+parameter-shift remains what the course teaches, what validates this, and what
+keeps the library hardware-ready.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+import numpy.typing as npt
+
+from qmlkit.core.backends.base import Backend
+from qmlkit.core.backends.numpy_backend import _apply
+from qmlkit.core.backends.registry import get_backend
+from qmlkit.core.gates import gate_derivative, gate_matrix
+from qmlkit.core.ir import CircuitSpec, ParamRef
+from qmlkit.core.observables import Observable, PauliString, Z, as_sum
+
+__all__ = ["adjoint_grad", "supports_adjoint"]
+
+_PAULI = {
+    "I": np.eye(2, dtype=complex),
+    "X": np.array([[0, 1], [1, 0]], dtype=complex),
+    "Y": np.array([[0, -1j], [1j, 0]], dtype=complex),
+    "Z": np.array([[1, 0], [0, -1]], dtype=complex),
+}
+
+
+def supports_adjoint(spec: CircuitSpec, backend: Backend | str | None = None) -> bool:
+    """True if every parameterised gate in ``spec`` has a closed-form derivative."""
+    from qmlkit.core.gates import get_gate
+
+    be = get_backend(backend)
+    if not be.supports_statevector:
+        return False
+    return all(get_gate(s.gate).has_derivative for s in spec.slots())
+
+
+def _apply_observable(state: npt.NDArray[Any], obs: Observable, n_qubits: int) -> npt.NDArray[Any]:
+    """``O|psi>`` for a Pauli sum, in tensor shape."""
+    total = np.zeros_like(state)
+    for term in as_sum(obs).terms:
+        out = state
+        for q, p in term.paulis:
+            if p == "I":
+                continue
+            out = np.tensordot(_PAULI[p], out, axes=([1], [q]))
+            out = np.moveaxis(out, 0, q)
+        total = total + term.coeff * out
+    return total
+
+
+def adjoint_grad(
+    spec: CircuitSpec,
+    theta: npt.NDArray[Any],
+    obs: Observable | None = None,
+    backend: Backend | str | None = None,
+) -> npt.NDArray[Any]:
+    """Exact gradient of ``<obs>`` with respect to the logical parameter vector.
+
+    One forward pass and one backward pass, whatever ``P`` is. Weight-tied
+    parameters accumulate across their occurrences, exactly as parameter-shift does.
+    """
+    obs = Z(0) if obs is None else obs
+    be = get_backend(backend)
+    if not be.supports_statevector:
+        raise ValueError(
+            f"the {be.name!r} backend has no statevector, so it cannot differentiate by "
+            'the adjoint method; use grad_method="parameter-shift"'
+        )
+
+    theta = np.asarray(theta, dtype=float).ravel()
+    slots = spec.slots()
+    slot_angles = spec.bind_slots(theta)
+    n = spec.n_qubits
+    shape = (2,) * n
+
+    # forward: run the bound circuit once
+    psi = be.statevector(spec.with_slot_angles(slot_angles)).reshape(shape)
+    lam = _apply_observable(psi, obs, n)
+
+    grad = np.zeros(spec.n_params, dtype=float)
+    slot_of_op = {s.op_index: i for i, s in enumerate(slots)}
+
+    # backward: undo one gate at a time, reading off each parameter's contribution
+    cursor = len(slot_angles)
+    for op_index in range(len(spec.ops) - 1, -1, -1):
+        op = spec.ops[op_index]
+        slot_i = slot_of_op.get(op_index)
+        if slot_i is not None:
+            cursor -= 1
+            angles = [float(slot_angles[cursor])]
+        else:
+            angles = [float(p) for p in op.params if not isinstance(p, ParamRef)]
+
+        u = gate_matrix(op.gate, tuple(angles))
+        psi = _apply(psi, u.conj().T, op.qubits)  # psi is now the state before this gate
+
+        if slot_i is not None:
+            du = gate_derivative(op.gate, tuple(angles))
+            mu = _apply(psi, du, op.qubits)
+            contribution = 2.0 * float(np.real(np.vdot(lam, mu)))
+            ref = slots[slot_i].ref
+            grad[ref.index] += contribution * ref.scale  # += ties occurrences together
+
+        lam = _apply(lam, u.conj().T, op.qubits)
+
+    return grad
+
+
+def adjoint_grad_terms(
+    spec: CircuitSpec,
+    theta: npt.NDArray[Any],
+    obs: Observable,
+    backend: Backend | str | None = None,
+) -> dict[PauliString, npt.NDArray[Any]]:  # pragma: no cover - convenience for diagnostics
+    """Per-term gradients, for diagnosing which observable term drives a parameter."""
+    return {t: adjoint_grad(spec, theta, t, backend) for t in as_sum(obs).terms}

qmlkit/gradients/batch.py

@@ -0,0 +1,275 @@
+r"""Gradients for a whole training batch, in one pass rather than one per sample.
+
+A training step evaluates the same circuit *structure* at one parameter vector per
+sample. The forward pass has been batched for a while; the backward pass had not, and
+the backward pass is where the time goes — measured on a 4-qubit ``VQC`` at batch 128,
+the forward pass was 13 ms of an 1170 ms step. **99% of training was still running one
+sample at a time.**
+
+Two routes, and the difference between them is the point of this module.
+
+:func:`param_shift_grad_batch` is **backend-agnostic**. A shift rule only ever needs
+the circuit *run* at shifted angles, so a whole batch's gradient is one big set of
+evaluations — ``batch x 2P`` of them — with no inspection of the state at all. It goes
+through :meth:`~qmlkit.core.backends.base.Backend.expectation_over_slots`, which every
+backend has, so this works on NumPy, Qiskit, Cirq, SpinQit, a sampling-only device, and
+anything registered later. On hardware it is exactly the batched submission a provider
+wants: one job instead of ``batch x 2P`` blocking calls.
+
+:func:`adjoint_grad_batch` is faster and simulator-only, because it reads the state.
+
+Both are exact, and both are asserted equal to the per-sample functions they replace.
+
+The shifts happen in **slot** space, not logical-parameter space, which is why the
+batch primitives underneath are slot-based. A shift rule moves one *occurrence* of a
+parameter and a weight-tied parameter has several; a batched routine written against
+logical parameters cannot express that, and would silently compute a different
+derivative for any circuit with shared weights.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+import numpy.typing as npt
+from numpy.typing import ArrayLike
+
+from qmlkit.core.backends.base import Backend
+from qmlkit.core.backends.numpy_backend import (
+    _VECTORISED_D,
+    _apply_batch,
+    _batched_matrices,
+)
+from qmlkit.core.backends.registry import get_backend
+from qmlkit.core.gates import gate_derivative
+from qmlkit.core.ir import CircuitSpec, Op
+from qmlkit.core.observables import Observable, Z, as_sum
+from qmlkit.gradients.rules import rule_for_gate
+
+__all__ = ["grad_batch", "param_shift_grad_batch", "adjoint_grad_batch"]
+
+_PAULI = {
+    "I": np.eye(2, dtype=complex),
+    "X": np.array([[0, 1], [1, 0]], dtype=complex),
+    "Y": np.array([[0, -1j], [1j, 0]], dtype=complex),
+    "Z": np.array([[1, 0], [0, -1]], dtype=complex),
+}
+
+
+# --------------------------------------------------------------------------- #
+# the backend-agnostic route
+# --------------------------------------------------------------------------- #
+def param_shift_grad_batch(
+    spec: CircuitSpec,
+    thetas: ArrayLike,
+    obs: Observable | None = None,
+    shots: int | None = None,
+    backend: Backend | str | None = None,
+    seed: int | None = None,
+) -> npt.NDArray[Any]:
+    """Parameter-shift gradients for a batch, as **one** set of evaluations.
+
+    Returns ``(batch, n_params)``.
+
+    Every shifted circuit the whole batch needs is assembled first and handed to the
+    backend in a single call, so a backend that can evaluate many circuits at once —
+    or submit them as one job — gets to. Nothing here inspects a state, so this is
+    valid on hardware and under sampling.
+
+    Weight-tied parameters accumulate across occurrences and rescaled references get
+    their chain-rule factor, exactly as the per-sample
+    :func:`~qmlkit.gradients.parameter_shift.param_shift_grad` does.
+    """
+    obs = Z(0) if obs is None else obs
+    be = get_backend(backend)
+    angles = spec.bind_slots_batch(np.atleast_2d(np.asarray(thetas, dtype=float)))
+    batch = angles.shape[0]
+    slots = spec.slots()
+    if not slots:
+        return np.zeros((batch, spec.n_params), dtype=float)
+
+    # ---- assemble every shifted row the batch needs, once ------------------ #
+    blocks: list[npt.NDArray[Any]] = []
+    plan: list[tuple[int, float]] = []  # (slot index, coefficient)
+    needs_unshifted = False
+    for i, slot in enumerate(slots):
+        rule = rule_for_gate(slot.gate)
+        for shift, coeff in zip(rule.shifts, rule.coeffs, strict=False):
+            shifted = angles.copy()
+            shifted[:, i] += shift
+            blocks.append(shifted)
+            plan.append((i, coeff))
+        needs_unshifted = needs_unshifted or rule.needs_unshifted
+    if needs_unshifted:
+        blocks.append(angles)
+
+    values = be.expectation_over_slots(
+        spec, np.concatenate(blocks, axis=0), obs, shots, seed
+    ).reshape(len(blocks), batch)
+
+    # ---- fold the evaluations back into per-parameter gradients ------------ #
+    grad = np.zeros((batch, spec.n_params), dtype=float)
+    for k, (i, coeff) in enumerate(plan):
+        ref = slots[i].ref
+        grad[:, ref.index] += coeff * values[k] * ref.scale
+    if needs_unshifted:
+        base = values[-1]
+        for slot in slots:
+            rule = rule_for_gate(slot.gate)
+            if rule.needs_unshifted:
+                grad[:, slot.ref.index] += rule.unshifted_coeff * base * slot.ref.scale
+    return grad
+
+
+def param_shift_batch_cost(spec: CircuitSpec, batch: int) -> int:
+    """Circuit evaluations a batched parameter-shift gradient submits, in total."""
+    per_sample = sum(rule_for_gate(s.gate).n_evaluations for s in spec.slots())
+    return per_sample * batch
+
+
+# --------------------------------------------------------------------------- #
+# the simulator route
+# --------------------------------------------------------------------------- #
+def _apply_observable_batch(
+    state: npt.NDArray[Any], obs: Observable, n_qubits: int
+) -> npt.NDArray[Any]:
+    """``O|psi>`` for a stack of states, Pauli term by Pauli term."""
+    total = np.zeros_like(state)
+    for term in as_sum(obs).terms:
+        out = state
+        for q, p in term.paulis:
+            if p == "I":
+                continue
+            out = np.tensordot(_PAULI[p], out, axes=([1], [q + 1]))
+            out = np.moveaxis(out, 0, q + 1)
+        total = total + term.coeff * out
+    return total
+
+
+def _dagger(matrices: npt.NDArray[Any]) -> npt.NDArray[Any]:
+    """Conjugate transpose, whether the array is one matrix or a stack of them."""
+    if matrices.ndim == 2:
+        return matrices.conj().T
+    return matrices.conj().transpose(0, 2, 1)
+
+
+def _batched_derivatives(op: Op, columns: npt.NDArray[Any]) -> npt.NDArray[Any]:
+    """``dU/dtheta`` per row, in closed form where one is registered.
+
+    Profiling the batched adjoint put four times as much time in building these one
+    row at a time as in the contraction they feed, which is why the vectorised table
+    exists. A gate outside it still works, one build per row.
+    """
+    builder = _VECTORISED_D.get(op.gate)
+    if builder is not None and columns.shape[1] == 1:
+        return builder(columns[:, 0])
+    return np.stack([gate_derivative(op.gate, tuple(row)) for row in columns])
+
+
+def adjoint_grad_batch(
+    spec: CircuitSpec,
+    thetas: ArrayLike,
+    obs: Observable | None = None,
+    backend: Backend | str | None = None,
+) -> npt.NDArray[Any]:
+    """Adjoint gradients for a batch in one forward and one backward sweep.
+
+    Returns ``(batch, n_params)``. Exact, and independent of ``P`` in cost, but it
+    needs the statevector — so it is simulator-only, and
+    :func:`param_shift_grad_batch` is what a device uses.
+
+    The sweep is the one in :mod:`~qmlkit.gradients.adjoint` with the batch carried as
+    a leading axis: every gate is undone for the whole stack at once, and each
+    parameter's contribution comes out as one inner product per row.
+    """
+    obs = Z(0) if obs is None else obs
+    be = get_backend(backend)
+    if not be.supports_statevector:
+        raise ValueError(
+            f"the {be.name!r} backend has no statevector, so it cannot differentiate by "
+            'the adjoint method; use method="parameter-shift", which batches too'
+        )
+
+    values = np.atleast_2d(np.asarray(thetas, dtype=float))
+    angles = spec.bind_slots_batch(values)
+    batch, n = angles.shape[0], spec.n_qubits
+    slots = spec.slots()
+
+    psi = be.statevector_batch_slots(spec, angles).reshape((batch,) + (2,) * n)
+    lam = _apply_observable_batch(psi, obs, n)
+    grad = np.zeros((batch, spec.n_params), dtype=float)
+
+    # walk the slots backwards in step with the ops, the way the scalar version does
+    cursor = len(slots)
+    for op_index in range(len(spec.ops) - 1, -1, -1):
+        op = spec.ops[op_index]
+        first = cursor
+        while first > 0 and slots[first - 1].op_index == op_index:
+            first -= 1
+        columns = angles[:, first:cursor] if first < cursor else None
+        cursor = first
+
+        u = _batched_matrices(op, columns)
+        psi = _apply_batch(psi, _dagger(u), op.qubits)  # the state before this gate
+
+        if columns is not None and columns.shape[1] == 1:
+            du = _batched_derivatives(op, columns)
+            mu = _apply_batch(psi, du, op.qubits)
+            overlap = np.einsum("bi,bi->b", lam.reshape(batch, -1).conj(), mu.reshape(batch, -1))
+            ref = slots[first].ref
+            grad[:, ref.index] += 2.0 * np.real(overlap) * ref.scale
+        elif columns is not None and columns.shape[1] > 1:  # pragma: no cover
+            raise NotImplementedError(
+                f"gate {op.gate!r} has {columns.shape[1]} parameters; batched adjoint "
+                'handles one per gate. Use method="parameter-shift".'
+            )
+
+        lam = _apply_batch(lam, _dagger(u), op.qubits)
+    return grad
+
+
+# --------------------------------------------------------------------------- #
+# dispatch
+# --------------------------------------------------------------------------- #
+def grad_batch(
+    spec: CircuitSpec,
+    thetas: ArrayLike,
+    obs: Observable | None = None,
+    method: str = "auto",
+    shots: int | None = None,
+    backend: Backend | str | None = None,
+    seed: int | None = None,
+) -> npt.NDArray[Any]:
+    """``(batch, n_params)`` gradients, by whichever route fits the backend.
+
+    ``"auto"`` picks adjoint on an exact simulator and parameter-shift otherwise —
+    the same rule :func:`~qmlkit.gradients.dispatch.choose_method` uses for one
+    sample, since sampling puts the statevector out of reach by definition.
+
+        >>> import numpy as np, qmlkit as qk
+        >>> a = qk.hardware_efficient(3, 2)
+        >>> qk.grad_batch(a.build(), np.zeros((5, a.n_params)), qk.Z(0)).shape
+        (5, 12)
+    """
+    if method == "auto":
+        from qmlkit.gradients.adjoint import supports_adjoint
+
+        method = (
+            "adjoint" if shots is None and supports_adjoint(spec, backend) else "parameter-shift"
+        )
+    if method == "adjoint":
+        if shots is not None:
+            raise ValueError("adjoint differentiation is exact; it cannot take shots")
+        return adjoint_grad_batch(spec, thetas, obs, backend)
+    if method == "parameter-shift":
+        return param_shift_grad_batch(spec, thetas, obs, shots, backend, seed)
+
+    from qmlkit.utils.errors import unknown
+
+    raise unknown(
+        "batched gradient method",
+        method,
+        ("auto", "adjoint", "parameter-shift"),
+        hint=" Other methods have no batched form yet; loop over qk.grad for those.",
+    )

qmlkit/gradients/dispatch.py

@@ -0,0 +1,247 @@
+"""One gradient function, several methods, and a registry for adding more.
+
+    qk.grad(spec, theta, obs)                      # picks the right method for you
+    qk.grad(spec, theta, obs, method="parameter-shift")
+
+``method="auto"`` (the default) uses adjoint when every gate has a closed-form
+derivative and the backend can hand back a statevector — exact, and independent of
+the parameter count. It falls back to parameter-shift otherwise, which is exact
+too, just ``2P`` circuits instead of one pass.
+
+A researcher with a different estimator registers it and it becomes a keyword
+everywhere the library takes ``method=``:
+
+    @register_gradient("my_estimator")
+    def my_estimator(spec, theta, obs, *, backend=None, shots=None, **kw):
+        ...
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from typing import Any
+
+import numpy as np
+import numpy.typing as npt
+from numpy.typing import ArrayLike
+
+from qmlkit.core.backends.base import Backend
+from qmlkit.core.ir import CircuitSpec
+from qmlkit.core.observables import Observable, Z
+from qmlkit.utils.errors import unknown
+
+__all__ = [
+    "grad",
+    "register_gradient",
+    "list_gradient_methods",
+    "choose_method",
+    "hessian",
+    "gradient_cost",
+]
+
+GradFn = Callable[..., npt.NDArray[Any]]
+_METHODS: dict[str, GradFn] = {}
+
+
+def register_gradient(name: str, fn: GradFn | None = None) -> Callable[[GradFn], GradFn] | GradFn:
+    """Register a gradient estimator under ``name``. Usable as a decorator."""
+
+    def _register(f: GradFn) -> GradFn:
+        if name in _METHODS:
+            raise ValueError(f"gradient method {name!r} is already registered")
+        _METHODS[name] = f
+        return f
+
+    return _register if fn is None else _register(fn)
+
+
+def list_gradient_methods() -> tuple[str, ...]:
+    return tuple(sorted(_METHODS))
+
+
+def choose_method(
+    spec: CircuitSpec, backend: Backend | str | None = None, shots: int | None = None
+) -> str:
+    """What ``method="auto"`` resolves to, and why.
+
+    Sampling means the statevector is off the table by definition, so shots force
+    parameter-shift.
+    """
+    if shots is not None:
+        return "parameter-shift"
+    from qmlkit.gradients.adjoint import supports_adjoint
+
+    return "adjoint" if supports_adjoint(spec, backend) else "parameter-shift"
+
+
+def grad(
+    spec: CircuitSpec,
+    theta: ArrayLike,
+    obs: Observable | None = None,
+    method: str = "auto",
+    backend: Backend | str | None = None,
+    shots: int | None = None,
+    **kwargs: object,
+) -> npt.NDArray[Any]:
+    """Gradient of ``<obs>`` with respect to ``theta``.
+
+    Parameters
+    ----------
+    method
+        ``auto`` (default), ``adjoint``, ``parameter-shift``, ``spsa``, or
+        ``finite-diff``. Registered methods are accepted by name too.
+    shots
+        Sampling budget. Anything other than ``None`` rules out adjoint.
+    """
+    obs = Z(0) if obs is None else obs
+    resolved = choose_method(spec, backend, shots) if method == "auto" else method
+    try:
+        fn = _METHODS[resolved]
+    except KeyError:
+        raise unknown(
+            "gradient method",
+            resolved,
+            list_gradient_methods(),
+            hint='"auto" chooses for you; add your own with register_gradient(name, fn).',
+            error=KeyError,
+        ) from None
+    return fn(spec, np.asarray(theta, dtype=float), obs, backend=backend, shots=shots, **kwargs)
+
+
+# --------------------------------------------------------------------------- #
+# the built-in methods
+# --------------------------------------------------------------------------- #
+@register_gradient("adjoint")
+def _adjoint(spec, theta, obs, *, backend=None, shots=None, **kw):  # type: ignore[no-untyped-def]
+    from qmlkit.gradients.adjoint import adjoint_grad
+
+    if shots is not None:
+        raise ValueError(
+            "adjoint differentiation reads the statevector, so it cannot honour a shot "
+            'budget; use method="parameter-shift" with shots=N'
+        )
+    return adjoint_grad(spec, theta, obs, backend)
+
+
+@register_gradient("parameter-shift")
+def _param_shift(spec, theta, obs, *, backend=None, shots=None, seed=None, **kw):  # type: ignore[no-untyped-def]
+    from qmlkit.gradients.parameter_shift import param_shift_grad_circuit
+
+    return param_shift_grad_circuit(spec, theta, obs, shots=shots, backend=backend, seed=seed)
+
+
+@register_gradient("finite-diff")
+def _finite_diff(spec, theta, obs, *, backend=None, shots=None, eps=1e-6, **kw):  # type: ignore[no-untyped-def]
+    from qmlkit.core.execute import expval
+    from qmlkit.gradients.parameter_shift import finite_diff_grad
+
+    def f(t: npt.NDArray[Any]) -> float:
+        return expval(spec, obs, theta=t, shots=shots, backend=backend)
+
+    return finite_diff_grad(f, theta, eps=eps)
+
+
+@register_gradient("spsa")
+def _spsa(spec, theta, obs, *, backend=None, shots=None, c=0.1, n_avg=1, seed=None, **kw):  # type: ignore[no-untyped-def]
+    from qmlkit.core.execute import expval
+    from qmlkit.gradients.spsa import spsa_grad
+
+    def f(t: npt.NDArray[Any]) -> float:
+        return expval(spec, obs, theta=t, shots=shots, backend=backend, seed=seed)
+
+    return spsa_grad(f, theta, c=c, n_avg=n_avg, seed=seed)
+
+
+@register_gradient("hadamard")
+def _hadamard(spec, theta, obs, *, backend=None, shots=None, seed=None, **kw):  # type: ignore[no-untyped-def]
+    from qmlkit.gradients.hadamard import hadamard_grad
+
+    return hadamard_grad(spec, theta, obs, backend=backend, shots=shots, seed=seed)
+
+
+@register_gradient("backprop")
+def _backprop(spec, theta, obs, *, backend=None, shots=None, **kw):  # type: ignore[no-untyped-def]
+    """Differentiate the torch statevector simulator directly.
+
+    This method needs an autograd-traced statevector, so it always evaluates on the
+    torch simulator whichever statevector backend is selected — the number is the same
+    because they agree, but the *device* is not honoured. On a backend that has no
+    statevector at all that difference stops being cosmetic: returning a machine-precision
+    gradient computed on a simulator, to a caller who asked for one from hardware, is
+    exactly the plausible-wrong-number failure this library exists to refuse. So it is
+    refused, the same way ``adjoint`` is.
+    """
+    from qmlkit.core.backends.base import BackendNotAvailable
+    from qmlkit.core.backends.registry import get_backend
+
+    device = get_backend(backend)
+    if not device.supports_statevector:
+        raise ValueError(
+            f"the {device.name!r} backend has no statevector, so it cannot differentiate "
+            'by backprop; use method="parameter-shift", which is measurement-only and '
+            "batches into one submission"
+        )
+
+    try:
+        import torch
+    except ImportError as exc:  # pragma: no cover - depends on the environment
+        # `backprop` is registered unconditionally, so it shows up in
+        # list_gradient_methods() on a bare install too. Anyone iterating those
+        # methods deserves the install command rather than a raw ModuleNotFoundError.
+        raise BackendNotAvailable(
+            "the backprop gradient needs PyTorch:\n    pip install 'qmlkit[torch]'"
+        ) from exc
+
+    from qmlkit.core.backends.torch_backend import torch_expectation
+
+    if shots is not None:
+        raise ValueError(
+            "backprop differentiates the statevector, so it cannot honour a shot "
+            'budget; use method="parameter-shift" with shots=N'
+        )
+    t = torch.tensor(np.asarray(theta, dtype=float), dtype=torch.float64, requires_grad=True)
+    torch_expectation(spec, t, obs).backward()
+    assert t.grad is not None
+    return t.grad.detach().cpu().numpy()
+
+
+def hessian(
+    spec: CircuitSpec,
+    theta: Sequence[float],
+    obs: Observable | None = None,
+    backend: Backend | str | None = None,
+    eps: float = 1e-4,
+) -> npt.NDArray[Any]:
+    """Second derivatives, by differencing the exact gradient.
+
+    The gradient itself is exact (adjoint), so only the outer derivative is
+    approximated — far more accurate than differencing the expectation twice.
+    """
+    obs = Z(0) if obs is None else obs
+    arr = np.asarray(theta, dtype=float).ravel()
+    p = arr.size
+    out = np.zeros((p, p))
+    for k in range(p):
+        plus, minus = arr.copy(), arr.copy()
+        plus[k] += eps
+        minus[k] -= eps
+        out[k] = (
+            grad(spec, plus, obs, backend=backend) - grad(spec, minus, obs, backend=backend)
+        ) / (2 * eps)
+    return 0.5 * (out + out.T)  # symmetrise away the differencing asymmetry
+
+
+def gradient_cost(spec: CircuitSpec, method: str = "parameter-shift") -> int | str:
+    """Circuit evaluations one gradient needs under a given method."""
+    from qmlkit.gradients.hadamard import hadamard_grad_cost
+    from qmlkit.gradients.parameter_shift import grad_circuit_cost
+
+    costs = {
+        "adjoint": 1,
+        "backprop": 1,
+        "hadamard": hadamard_grad_cost(spec),
+        "parameter-shift": grad_circuit_cost(spec),
+        "finite-diff": 2 * spec.n_params,
+        "spsa": 2,
+    }
+    return costs.get(method, "unknown")