qmlkit 0.1.0__py3-none-any.whl

qmlkit/algorithms/adapt.py

@@ -0,0 +1,297 @@
+r"""ADAPT-VQE — grow the ansatz instead of guessing it.
+
+A fixed ansatz is a bet placed before you have seen the Hamiltonian. ADAPT-VQE
+(Grimsley et al. 2019) makes the circuit itself part of the optimisation: keep a pool
+of candidate generators, and at each iteration append the one whose gradient is
+largest, then re-optimise everything.
+
+The gradient of appending :math:`e^{-i\theta P/2}` to the current state, evaluated at
+:math:`\theta = 0`, is
+
+.. math::  \left.\frac{\partial E}{\partial\theta}\right|_0 = -i\langle\psi|[H, P]|\psi\rangle
+
+so ranking the pool costs one commutator expectation per candidate — no re-training
+to find out which operator would have helped.
+
+This is the algorithm that most depends on a circuit being *data*: growing an ansatz
+mid-optimisation is a list append here, not a rebuild.
+"""
+
+from __future__ import annotations
+
+import itertools
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from typing import Any
+
+import numpy as np
+import numpy.typing as npt
+
+from qmlkit.algorithms.hamiltonians import exact_ground_energy
+from qmlkit.algorithms.vqe import OPTIMIZERS, Optimizer
+from qmlkit.ansatz.blocks import BuildContext, Custom
+from qmlkit.ansatz.library import Ansatz
+from qmlkit.core.builder import QCircuit
+from qmlkit.core.execute import BackendLike, expectation
+from qmlkit.core.observables import Observable, PauliString, PauliSum, as_sum
+
+__all__ = [
+    "AdaptVQE",
+    "AdaptResult",
+    "pauli_rotation",
+    "default_operator_pool",
+    "chemistry_operator_pool",
+]
+
+
+def pauli_rotation(qc: QCircuit, term: PauliString, angle: Any) -> None:
+    r"""Emit :math:`e^{-i\theta P/2}` for an arbitrary Pauli string ``P``.
+
+    The standard construction: rotate each wire into the Z basis, run a CX ladder to
+    collect the parity onto one wire, apply a single ``rz``, then undo both. Built
+    from ordinary registered gates, so it runs on every backend.
+    """
+    wires = [q for q, p in term.paulis if p != "I"]
+    if not wires:
+        return
+    for qubit, pauli in term.paulis:
+        if pauli == "X":
+            qc.h(qubit)
+        elif pauli == "Y":
+            qc.sdg(qubit)
+            qc.h(qubit)
+    for a, b in zip(wires, wires[1:], strict=False):
+        qc.cx(a, b)
+    qc.rz(wires[-1], angle)
+    for a, b in reversed(list(zip(wires, wires[1:], strict=False))):
+        qc.cx(a, b)
+    for qubit, pauli in term.paulis:
+        if pauli == "X":
+            qc.h(qubit)
+        elif pauli == "Y":
+            qc.h(qubit)
+            qc.s(qubit)
+
+
+def default_operator_pool(n_qubits: int) -> list[PauliString]:
+    """Single-qubit ``Y`` and neighbouring ``YZ`` generators.
+
+    Deliberately all imaginary-valued generators: those are the ones that move a real
+    starting state, which is what a real-amplitude ground state needs. The pool is an
+    argument, so a chemistry-flavoured (UCCSD-style) pool drops straight in.
+    """
+    # Note these do *not* conserve particle number, so they are useless on a
+    # molecular Hamiltonian -- see chemistry_operator_pool.
+    pool = [PauliString(((q, "Y"),), 1.0) for q in range(n_qubits)]
+    pool += [PauliString(((q, "Y"), (q + 1, "Z")), 1.0) for q in range(n_qubits - 1)]
+    pool += [PauliString(((q, "Y"), (q + 1, "X")), 1.0) for q in range(n_qubits - 1)]
+    return pool
+
+
+def chemistry_operator_pool(n_qubits: int) -> list[PauliString]:
+    r"""A particle-number-conserving pool, for molecular Hamiltonians.
+
+    :func:`default_operator_pool` is generic and *wrong for chemistry*: a molecular
+    Hamiltonian commutes with the number operator, so any generator that changes
+    particle number has exactly zero gradient at the Hartree-Fock state. Measured on
+    H\ :sub:`2`: every operator in the default pool scores ``0.00e+00``, ADAPT
+    correctly concludes nothing helps, and returns an empty circuit.
+
+    This is the qubit-ADAPT pool of Tang et al. (2021) — the individual Pauli strings
+    appearing in single and double excitations, which under Jordan-Wigner carry an
+    **odd number of Y factors**. On H\ :sub:`2` the winning operator is the double
+    excitation ``Y0 X1 X2 X3``, and one parameter is enough to reach the exact ground
+    state.
+    """
+    pool: list[PauliString] = []
+    for p_, q_ in itertools.combinations(range(n_qubits), 2):  # singles
+        pool.append(PauliString(((p_, "Y"), (q_, "X")), 1.0))
+        pool.append(PauliString(((p_, "X"), (q_, "Y")), 1.0))
+    for quad in itertools.combinations(range(n_qubits), 4):  # doubles
+        for y_at in range(4):
+            paulis = tuple((wire, "Y" if index == y_at else "X") for index, wire in enumerate(quad))
+            pool.append(PauliString(paulis, 1.0))
+    return pool
+
+
+@dataclass
+class AdaptResult:
+    energy: float
+    theta: npt.NDArray[Any]
+    operators: list[PauliString] = field(default_factory=list)
+    history: list[float] = field(default_factory=list)
+    gradients: list[float] = field(default_factory=list)
+    exact: float | None = None
+
+    @property
+    def error_vs_exact(self) -> float | None:
+        return None if self.exact is None else abs(self.energy - self.exact)
+
+    @property
+    def n_operators(self) -> int:
+        return len(self.operators)
+
+    def __repr__(self) -> str:
+        tail = "" if self.exact is None else f", error={self.error_vs_exact:.2e}"
+        return f"AdaptResult(energy={self.energy:.8f}, operators={self.n_operators}{tail})"
+
+
+class AdaptVQE:
+    """Build the ansatz one operator at a time, largest gradient first."""
+
+    def __init__(
+        self,
+        hamiltonian: Observable,
+        n_qubits: int,
+        pool: Sequence[PauliString] | None = None,
+        optimizer: str | Optimizer = "gradient-descent",
+        backend: BackendLike = None,
+        reference: Sequence[int] | None = None,
+    ) -> None:
+        self.hamiltonian = hamiltonian
+        self.n_qubits = n_qubits
+        self.pool = list(pool) if pool is not None else default_operator_pool(n_qubits)
+        self.optimizer = optimizer
+        self.backend = backend
+        #: the starting state, as bits. Hartree-Fock plays this role in chemistry.
+        self.reference = list(reference) if reference is not None else []
+
+    # -------------------------------------------------------------- machinery --
+    def _ansatz(self, operators: Sequence[PauliString]) -> Ansatz:
+        """The circuit built from the operators chosen so far — a list, not a class."""
+        reference = self.reference
+
+        def build(qc: QCircuit, ctx: BuildContext) -> None:
+            for wire in reference:
+                qc.x(wire)
+            for term in operators:
+                pauli_rotation(qc, term, ctx.new_param())
+
+        return Ansatz(self.n_qubits, Custom(build, "adapt"), "adapt")
+
+    def _commutator_gradient(
+        self, operators: Sequence[PauliString], theta: npt.NDArray[Any], candidate: PauliString
+    ) -> float:
+        r"""``|<psi|[H, P]|psi>|`` — how much appending ``P`` would move the energy."""
+        commutator = _commutator(self.hamiltonian, candidate)
+        if not commutator.terms:
+            return 0.0
+        spec = self._ansatz(operators).build(theta) if len(operators) else self._ansatz([]).build()
+        return abs(float(expectation(spec, commutator, backend=self.backend)))
+
+    # -------------------------------------------------------------------- run --
+    def run(
+        self,
+        max_operators: int = 8,
+        gradient_tol: float = 1e-3,
+        seed: int | None = None,
+        compare_exact: bool | None = None,
+        **optimizer_kwargs: Any,
+    ) -> AdaptResult:
+        operators: list[PauliString] = []
+        theta: npt.NDArray[Any] = np.zeros(0)
+        history: list[float] = []
+        picked_gradients: list[float] = []
+
+        base = self._ansatz([]).build()
+        history.append(float(expectation(base, self.hamiltonian, backend=self.backend)))
+
+        for _ in range(max_operators):
+            scores = [self._commutator_gradient(operators, theta, p) for p in self.pool]
+            best = int(np.argmax(scores))
+            if scores[best] < gradient_tol:
+                break  # nothing left in the pool moves the energy
+            operators.append(self.pool[best])
+            picked_gradients.append(float(scores[best]))
+
+            ansatz = self._ansatz(operators)
+            spec = ansatz.build()
+            start = np.concatenate([theta, [0.0]])  # a new operator starts at identity
+
+            def energy(t: Sequence[float], spec: Any = spec) -> float:
+                return float(
+                    expectation(
+                        spec, self.hamiltonian, theta=np.asarray(t, float), backend=self.backend
+                    )
+                )
+
+            def gradient(t: Sequence[float], spec: Any = spec) -> npt.NDArray[Any]:
+                from qmlkit.gradients.dispatch import grad
+
+                return grad(spec, np.asarray(t, float), self.hamiltonian, backend=self.backend)
+
+            fn = OPTIMIZERS[self.optimizer] if isinstance(self.optimizer, str) else self.optimizer
+            kwargs = dict(optimizer_kwargs)
+            if fn is OPTIMIZERS["gradient-descent"]:
+                kwargs.setdefault("grad", gradient)
+                kwargs.setdefault("n_steps", 60)
+                kwargs.setdefault("lr", 0.2)
+            if fn is OPTIMIZERS["spsa"]:
+                kwargs.setdefault("seed", seed)
+            theta, run_history = fn(energy, start, **kwargs)
+            history.append(float(run_history[-1]))
+
+        if compare_exact is None:
+            compare_exact = self.n_qubits <= 12
+        exact = exact_ground_energy(self.hamiltonian, self.n_qubits) if compare_exact else None
+
+        return AdaptResult(
+            energy=history[-1],
+            theta=theta,
+            operators=operators,
+            history=history,
+            gradients=picked_gradients,
+            exact=exact,
+        )
+
+    def __repr__(self) -> str:
+        return f"AdaptVQE(n_qubits={self.n_qubits}, pool={len(self.pool)} operators)"
+
+
+# --------------------------------------------------------------------------- #
+def _multiply(a: PauliString, b: PauliString) -> tuple[complex, PauliString]:
+    """Product of two Pauli strings, as ``(phase, string)``."""
+    table = {
+        ("X", "Y"): (1j, "Z"),
+        ("Y", "X"): (-1j, "Z"),
+        ("Y", "Z"): (1j, "X"),
+        ("Z", "Y"): (-1j, "X"),
+        ("Z", "X"): (1j, "Y"),
+        ("X", "Z"): (-1j, "Y"),
+    }
+    left, right = dict(a.paulis), dict(b.paulis)
+    phase = complex(a.coeff) * complex(b.coeff)
+    out: dict[int, str] = {}
+    for qubit in set(left) | set(right):
+        p, q = left.get(qubit), right.get(qubit)
+        if p is None or q is None:
+            out[qubit] = p or q  # type: ignore[assignment]
+        elif p == q:
+            continue  # P^2 = I
+        else:
+            factor, letter = table[(p, q)]
+            phase *= factor
+            out[qubit] = letter
+    return phase, PauliString(tuple(sorted(out.items())), 1.0)
+
+
+def _commutator(h: Observable, p: PauliString) -> PauliSum:
+    r"""``i[H, P]`` — the *Hermitian* combination, which is what can be measured.
+
+    ``[H, P]`` with both operands Hermitian is anti-Hermitian, so every coefficient it
+    produces is purely imaginary and its expectation value is imaginary too. Taking
+    the real part of that discards the whole thing: an early version of this function
+    did exactly that, and ADAPT-VQE then scored every candidate at zero and grew an
+    empty circuit. Multiplying by ``i`` first is what makes the result an observable.
+    """
+    collected: dict[tuple[tuple[int, str], ...], complex] = {}
+    for term in as_sum(h).terms:
+        for left, right, sign in ((term, p, 1.0), (p, term, -1.0)):
+            phase, product = _multiply(left, right)
+            collected[product.paulis] = collected.get(product.paulis, 0j) + sign * phase
+    terms = [
+        PauliString(paulis, float(np.real(1j * coeff)))
+        for paulis, coeff in collected.items()
+        if abs(np.real(1j * coeff)) > 1e-12
+    ]
+    return PauliSum(tuple(terms))

qmlkit/algorithms/autoencoder.py

@@ -0,0 +1,206 @@
+"""Quantum autoencoder — compress ``n`` qubits into ``k`` (Romero, Olson & Aspuru-Guzik 2017).
+
+The trick is that you never need the decoder to train. If the encoder has genuinely
+pushed all the information into ``k`` latent qubits, the discarded "trash" qubits must
+be left in a known pure state — so **maximising the trash qubits' purity is the whole
+loss**, and it costs no extra circuits.
+
+    from qmlkit.algorithms import QuantumAutoencoder
+
+    model = QuantumAutoencoder(n_qubits=4, n_latent=2)
+    result = model.fit(states, seed=0)
+    print(result.fidelity)       # how well the input survives a round trip
+
+The encoder is an ``Ansatz`` argument like everywhere else, so "which circuit
+compresses best" is an experiment you run, not a fork of this file.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from typing import Any
+
+import numpy as np
+import numpy.typing as npt
+from numpy.typing import ArrayLike
+
+from qmlkit.algorithms.vqe import OPTIMIZERS, Optimizer
+from qmlkit.ansatz.library import Ansatz, hardware_efficient
+from qmlkit.core.execute import BackendLike, expectation, statevector
+from qmlkit.core.ir import CircuitSpec, bound_angle
+from qmlkit.core.observables import Observable, PauliString, PauliSum
+from qmlkit.info import purity, state_fidelity
+
+__all__ = ["QuantumAutoencoder", "AutoencoderResult"]
+
+
+@dataclass
+class AutoencoderResult:
+    theta: npt.NDArray[Any]
+    trash_purity: float
+    fidelity: float
+    trash_fidelity: float = 0.0
+    history: list[float] = field(default_factory=list)
+
+    def __repr__(self) -> str:
+        return (
+            f"AutoencoderResult(trash_fidelity={self.trash_fidelity:.6f}, "
+            f"fidelity={self.fidelity:.6f}, steps={len(self.history) - 1})"
+        )
+
+
+class QuantumAutoencoder:
+    """Train an encoder that concentrates a state into ``n_latent`` qubits.
+
+    Parameters
+    ----------
+    n_qubits, n_latent
+        Width in, width kept. The remaining ``n_qubits - n_latent`` are the trash.
+    encoder
+        Any ``Ansatz`` of the right width. Defaults to hardware-efficient.
+    trash
+        Which wires to discard. Defaults to the last ones.
+    """
+
+    def __init__(
+        self,
+        n_qubits: int,
+        n_latent: int,
+        encoder: Ansatz | None = None,
+        n_layers: int = 3,
+        trash: Sequence[int] | None = None,
+        optimizer: str | Optimizer = "rotosolve",
+        backend: BackendLike = None,
+    ) -> None:
+        if not 0 < n_latent < n_qubits:
+            raise ValueError(f"n_latent must be between 1 and {n_qubits - 1}, got {n_latent}")
+        self.n_qubits = n_qubits
+        self.n_latent = n_latent
+        self.trash = list(trash) if trash is not None else list(range(n_latent, n_qubits))
+        self.encoder = encoder or hardware_efficient(n_qubits, n_layers)
+        self.optimizer = optimizer
+        self.backend = backend
+        self._spec = self.encoder.build()
+
+    # ------------------------------------------------------------------- loss --
+    def _trash_projector(self) -> Observable:
+        r"""The observable :math:`\prod_{i \in \mathrm{trash}} (I + Z_i)/2`.
+
+        This projects onto "every trash wire reads zero". Expanding the product gives
+        an ordinary Pauli sum, which matters more than it looks: the loss is then a
+        plain expectation value, so gradients come from :func:`qmlkit.grad` and
+        Rotosolve is valid — neither of which is true of a purity-based loss.
+        """
+        terms: list[PauliString] = []
+        scale = 0.5 ** len(self.trash)
+        for mask in range(2 ** len(self.trash)):
+            chosen = [w for i, w in enumerate(self.trash) if mask >> i & 1]
+            terms.append(PauliString(tuple((w, "Z") for w in sorted(chosen)), scale))
+        return PauliSum(tuple(terms))
+
+    def trash_fidelity(self, theta: ArrayLike, states: Sequence[CircuitSpec]) -> float:
+        r"""Mean :math:`\langle 0|
+        ho_\mathrm{trash}|0
+        angle` — 1.0 is perfect compression.
+
+                Purity alone is **not** enough, and getting that wrong is easy: an encoder can
+                leave the trash in a pure state pointing somewhere other than
+                :math:`|0
+        angle`, scoring purity 0.998 while the round trip only returns
+                fidelity 0.21. Measured, on the way to writing this. What the decoder needs is
+                the trash reset to a *known* state, so that is what the loss asks for.
+        """
+        arr = np.asarray(theta, dtype=float)
+        projector = self._trash_projector()
+        total = 0.0
+        for prep in states:
+            encoded = prep.compose(self._spec.bind(arr))
+            total += float(expectation(encoded, projector, backend=self.backend))
+        return total / len(states)
+
+    def trash_purity(self, theta: ArrayLike, states: Sequence[CircuitSpec]) -> float:
+        """Mean purity of the discarded wires. Reported, but not what is optimised."""
+        arr = np.asarray(theta, dtype=float)
+        total = 0.0
+        for prep in states:
+            encoded = prep.compose(self._spec.bind(arr))
+            total += purity(encoded, self.trash, backend=self.backend)
+        return total / len(states)
+
+    def loss(self, theta: Sequence[float], states: Sequence[CircuitSpec]) -> float:
+        """One minus the trash fidelity. No decoder is ever built to train this."""
+        return 1.0 - self.trash_fidelity(theta, states)
+
+    # -------------------------------------------------------------------- fit --
+    def fit(
+        self,
+        states: Sequence[CircuitSpec],
+        theta0: Sequence[float] | None = None,
+        seed: int | None = None,
+        **optimizer_kwargs: Any,
+    ) -> AutoencoderResult:
+        start = (
+            np.asarray(theta0, dtype=float)
+            if theta0 is not None
+            else self.encoder.init("small", seed=seed)
+        )
+        fn = OPTIMIZERS[self.optimizer] if isinstance(self.optimizer, str) else self.optimizer
+        if fn is OPTIMIZERS["spsa"]:
+            optimizer_kwargs.setdefault("seed", seed)
+        theta, history = fn(lambda t: self.loss(t, states), start, **optimizer_kwargs)
+
+        return AutoencoderResult(
+            theta=theta,
+            trash_purity=self.trash_purity(theta, states),
+            trash_fidelity=self.trash_fidelity(theta, states),
+            fidelity=self.round_trip_fidelity(theta, states),
+            history=list(history),
+        )
+
+    # ------------------------------------------------------------- validation --
+    def round_trip_fidelity(self, theta: ArrayLike, states: Sequence[CircuitSpec]) -> float:
+        """Encode, reset the trash to ``|0>``, decode, and compare to the input.
+
+        This is the quantity the compression *claims*, and it is deliberately not the
+        training loss — it is the independent check that maximising trash purity was
+        the right proxy at all.
+        """
+        arr = np.asarray(theta, dtype=float)
+        encoder = self._spec.bind(arr)
+        decoder = encoder.adjoint()
+        total = 0.0
+        for prep in states:
+            original = statevector(prep, backend=self.backend)
+            encoded = statevector(prep.compose(encoder), backend=self.backend)
+            restored = self._apply_spec(self._reset_trash(encoded), decoder)
+            total += state_fidelity(restored, original)
+        return total / len(states)
+
+    def _reset_trash(self, state: npt.NDArray[Any]) -> npt.NDArray[Any]:
+        """Project the trash wires onto ``|0>`` and renormalise."""
+        tensor = np.asarray(state).reshape((2,) * self.n_qubits)
+        keep: list[Any] = [slice(None)] * self.n_qubits
+        for wire in self.trash:
+            keep[wire] = 0
+        projected = np.zeros_like(tensor)
+        projected[tuple(keep)] = tensor[tuple(keep)]
+        flat = projected.reshape(-1)
+        norm = np.linalg.norm(flat)
+        return flat / norm if norm > 1e-12 else flat
+
+    def _apply_spec(self, state: npt.NDArray[Any], spec: CircuitSpec) -> npt.NDArray[Any]:
+        from qmlkit.core.backends.numpy_backend import _apply
+        from qmlkit.core.gates import gate_matrix
+
+        out = np.asarray(state, dtype=complex).reshape((2,) * self.n_qubits)
+        for op in spec.ops:
+            angles = tuple(bound_angle(p) for p in op.params)
+            out = _apply(out, gate_matrix(op.gate, angles), op.qubits)
+        return out.reshape(-1)
+
+    def __repr__(self) -> str:
+        return (
+            f"QuantumAutoencoder({self.n_qubits} -> {self.n_latent}, "
+            f"trash={self.trash}, encoder={self.encoder.name!r})"
+        )