qmlkit 0.1.0__py3-none-any.whl

qmlkit/algorithms/chemistry.py

@@ -0,0 +1,222 @@
+r"""Molecular Hamiltonians, computed here rather than quoted.
+
+VQE's canonical demonstration is the ground-state energy of H\ :sub:`2`, and most
+tutorials get the Hamiltonian by importing coefficients from a chemistry package or
+copying a table out of a paper. This module computes it: STO-3G integrals over
+Gaussian primitives, symmetry-adapted molecular orbitals, second quantisation, and a
+Jordan–Wigner map to four qubits.
+
+That matters for a library whose whole argument is that you should be able to see the
+cost of what you run. It is also checkable — the curve below reproduces the published
+FCI/STO-3G result to five decimals:
+
+    >>> from qmlkit.algorithms.chemistry import h2_hamiltonian
+    >>> from qmlkit.algorithms import exact_ground_energy
+    >>> h, info = h2_hamiltonian(0.735)
+    >>> round(exact_ground_energy(h, 4), 5)
+    -1.13731
+
+Minimal basis only, and two centres only. Anything larger wants PySCF or
+OpenFermion, and the point here is transparency rather than coverage.
+"""
+
+from __future__ import annotations
+
+import itertools
+import math
+from typing import Any
+
+import numpy as np
+import numpy.typing as npt
+
+from qmlkit.core.observables import PauliString, PauliSum
+
+__all__ = [
+    "h2_hamiltonian",
+    "h2_curve",
+    "BOHR_PER_ANGSTROM",
+    "HARTREE_TO_KCAL",
+    "CHEMICAL_ACCURACY",
+]
+
+#: STO-3G contraction for the hydrogen 1s orbital
+_ALPHA = np.array([3.42525091, 0.62391373, 0.16885540])
+_COEFF = np.array([0.15432897, 0.53532814, 0.44463454])
+_D = _COEFF * (2 * _ALPHA / np.pi) ** 0.75  # fold in the primitive normalisation
+
+BOHR_PER_ANGSTROM = 1.0 / 0.529177210903
+HARTREE_TO_KCAL = 627.509474
+#: 1 kcal/mol in hartree — the accuracy chemistry actually cares about
+CHEMICAL_ACCURACY = 1.0 / HARTREE_TO_KCAL
+
+_I2 = np.eye(2)
+_Z = np.diag([1.0, -1.0])
+_SIGMA_MINUS = np.array([[0.0, 1.0], [0.0, 0.0]])
+_PAULI: dict[str, npt.NDArray[Any]] = {
+    "I": _I2,
+    "X": np.array([[0.0, 1.0], [1.0, 0.0]]),
+    "Y": np.array([[0.0, -1j], [1j, 0.0]]),
+    "Z": _Z,
+}
+
+
+def _boys(t: float) -> float:
+    """Boys function :math:`F_0`, which is all s-type integrals need.
+
+    `math.erf` rather than SciPy's: qmlkit depends on NumPy alone, and reaching for
+    SciPy here would have added a runtime dependency for one scalar special function.
+    """
+    value = float(t)
+    if value < 1e-12:
+        return 1.0
+    return float(np.sqrt(np.pi / (4 * value)) * math.erf(np.sqrt(value)))
+
+
+def _kron(*matrices: npt.NDArray[Any]) -> npt.NDArray[Any]:
+    out = np.eye(1, dtype=complex)
+    for m in matrices:
+        out = np.kron(out, m)
+    return out
+
+
+def _ao_integrals(r_bohr: float) -> tuple[npt.NDArray[Any], ...]:
+    """Overlap, kinetic, nuclear attraction and two-electron integrals."""
+    centres = [np.array([0.0, 0.0, 0.0]), np.array([0.0, 0.0, r_bohr])]
+    n = 2
+    overlap = np.zeros((n, n))
+    kinetic = np.zeros((n, n))
+    nuclear = np.zeros((n, n))
+    for i, j in itertools.product(range(n), repeat=2):
+        diff = centres[i] - centres[j]
+        d2 = float(diff @ diff)
+        for a, da in zip(_ALPHA, _D, strict=True):
+            for b, db in zip(_ALPHA, _D, strict=True):
+                p = a + b
+                mu = a * b / p
+                gaussian = np.exp(-mu * d2)
+                s = (np.pi / p) ** 1.5 * gaussian
+                overlap[i, j] += da * db * s
+                kinetic[i, j] += da * db * mu * (3 - 2 * mu * d2) * s
+                centre = (a * centres[i] + b * centres[j]) / p
+                for nucleus in centres:  # both hydrogens carry Z = 1
+                    pc = centre - nucleus
+                    nuclear[i, j] -= (
+                        da * db * 2 * np.pi / p * gaussian * float(_boys(p * float(pc @ pc)))
+                    )
+
+    eri = np.zeros((n, n, n, n))
+    for i, j, k, m in itertools.product(range(n), repeat=4):
+        total = 0.0
+        dij = centres[i] - centres[j]
+        dkm = centres[k] - centres[m]
+        for a, da in zip(_ALPHA, _D, strict=True):
+            for b, db in zip(_ALPHA, _D, strict=True):
+                p = a + b
+                centre_p = (a * centres[i] + b * centres[j]) / p
+                k_ab = np.exp(-a * b / p * float(dij @ dij))
+                for c, dc in zip(_ALPHA, _D, strict=True):
+                    for d, dd in zip(_ALPHA, _D, strict=True):
+                        q = c + d
+                        centre_q = (c * centres[k] + d * centres[m]) / q
+                        k_cd = np.exp(-c * d / q * float(dkm @ dkm))
+                        pq = centre_p - centre_q
+                        total += (
+                            da
+                            * db
+                            * dc
+                            * dd
+                            * 2
+                            * np.pi**2.5
+                            / (p * q * np.sqrt(p + q))
+                            * k_ab
+                            * k_cd
+                            * float(_boys(p * q / (p + q) * float(pq @ pq)))
+                        )
+        eri[i, j, k, m] = total
+    return overlap, kinetic, nuclear, eri
+
+
+def _annihilator(orbital: int, n_spin_orbitals: int) -> npt.NDArray[Any]:
+    """Jordan-Wigner: a Z string for the fermionic sign, then a lowering operator."""
+    factors = [_Z] * orbital + [_SIGMA_MINUS] + [_I2] * (n_spin_orbitals - orbital - 1)
+    return _kron(*factors)
+
+
+def _matrix(bond_length_angstrom: float) -> tuple[npt.NDArray[Any], float]:
+    """The 16x16 Hamiltonian in the occupation-number basis, plus nuclear repulsion."""
+    r = bond_length_angstrom * BOHR_PER_ANGSTROM
+    overlap, kinetic, nuclear, eri = _ao_integrals(r)
+    core = kinetic + nuclear
+
+    # For a symmetric two-centre minimal basis the molecular orbitals are fixed by
+    # symmetry, so no SCF iteration is needed: sigma_g and sigma_u, normalised.
+    s = overlap[0, 1]
+    coefficients = np.array(
+        [
+            [1 / np.sqrt(2 * (1 + s)), 1 / np.sqrt(2 * (1 - s))],
+            [1 / np.sqrt(2 * (1 + s)), -1 / np.sqrt(2 * (1 - s))],
+        ]
+    )
+    h = coefficients.T @ core @ coefficients
+    g = np.einsum(
+        "pi,qj,rk,sl,pqrs->ijkl",
+        coefficients,
+        coefficients,
+        coefficients,
+        coefficients,
+        eri,
+        optimize=True,
+    )
+
+    n = 4  # two spatial orbitals, two spins
+    a = [_annihilator(p, n) for p in range(n)]
+    adag = [x.conj().T for x in a]
+    spin = (0, 1, 0, 1)
+    spatial = (0, 0, 1, 1)
+
+    matrix = np.zeros((2**n, 2**n), dtype=complex)
+    for p, q in itertools.product(range(n), repeat=2):
+        if spin[p] == spin[q]:
+            matrix += h[spatial[p], spatial[q]] * (adag[p] @ a[q])
+    for p, q, r_, s_ in itertools.product(range(n), repeat=4):
+        if spin[p] == spin[q] and spin[r_] == spin[s_]:
+            matrix += (
+                0.5
+                * g[spatial[p], spatial[q], spatial[r_], spatial[s_]]
+                * (adag[p] @ adag[r_] @ a[s_] @ a[q])
+            )
+    repulsion = 1.0 / r
+    return matrix + repulsion * np.eye(2**n), repulsion
+
+
+def h2_hamiltonian(
+    bond_length: float = 0.735, tol: float = 1e-10
+) -> tuple[PauliSum, dict[str, Any]]:
+    """The H2 qubit Hamiltonian at a given bond length in angstrom.
+
+    Returns the observable and a dictionary of what went into it. The Pauli
+    coefficients come from projecting the dense matrix, ``c_P = Tr(P H) / 2^n``,
+    which needs no symbolic algebra and is trivially checkable in the other
+    direction with :func:`~qmlkit.algorithms.hamiltonian_matrix`.
+    """
+    matrix, repulsion = _matrix(bond_length)
+    terms: list[PauliString] = []
+    for letters in itertools.product("IXYZ", repeat=4):
+        operator = _kron(*[_PAULI[c] for c in letters])
+        coefficient = float(np.real(np.trace(operator @ matrix)) / 16)
+        if abs(coefficient) > tol:
+            paulis = tuple((q, c) for q, c in enumerate(letters) if c != "I")
+            terms.append(PauliString(paulis, coefficient))
+    info = {
+        "bond_length": bond_length,
+        "n_qubits": 4,
+        "n_terms": len(terms),
+        "nuclear_repulsion": repulsion,
+        "hartree_fock_occupation": [1, 1, 0, 0],  # both electrons in sigma_g
+    }
+    return PauliSum(tuple(terms)), info
+
+
+def h2_curve(bond_lengths: npt.NDArray[Any] | list[float]) -> list[tuple[float, PauliSum]]:
+    """``(bond_length, hamiltonian)`` pairs — the dissociation curve as input data."""
+    return [(float(r), h2_hamiltonian(float(r))[0]) for r in bond_lengths]

qmlkit/algorithms/clustering.py

@@ -0,0 +1,149 @@
+"""q-means — Lloyd's algorithm with a quantum distance.
+
+The unsupervised gap. k-means is entirely defined by one operation, "how far apart
+are these two points", so replacing that with a quantum kernel distance is the whole
+algorithm:
+
+.. math::  d(x, x')^2 = 2\\bigl(1 - k(x, x')\\bigr)
+
+for a normalised kernel. Everything else — assign, recentre, repeat — is Lloyd's, and
+is deliberately unchanged so that any difference in the result is attributable to the
+distance and nothing else.
+
+The feature map is the argument, exactly as in :class:`~qmlkit.QSVC`: a clustering
+method built on a kernel *is* its embedding.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+import numpy as np
+import numpy.typing as npt
+
+from qmlkit.core.execute import BackendLike
+from qmlkit.encoding.feature_maps import FeatureMap
+from qmlkit.kernels.matrix import QuantumKernel
+
+__all__ = ["QMeans", "QMeansResult"]
+
+
+@dataclass
+class QMeansResult:
+    labels: npt.NDArray[Any]
+    centroids: npt.NDArray[Any]
+    inertia: float
+    n_iterations: int
+    history: list[float] = field(default_factory=list)
+
+    def __repr__(self) -> str:
+        return (
+            f"QMeansResult(k={len(self.centroids)}, inertia={self.inertia:.6f}, "
+            f"iterations={self.n_iterations})"
+        )
+
+
+class QMeans:
+    """k-means where the distance comes from a quantum kernel.
+
+    Parameters
+    ----------
+    n_clusters
+        ``k``.
+    feature_map
+        The embedding the distance is measured in. This is the only quantum part,
+        and swapping it is the entire experiment.
+    """
+
+    def __init__(
+        self,
+        n_clusters: int = 2,
+        feature_map: FeatureMap | None = None,
+        max_iterations: int = 50,
+        tol: float = 1e-6,
+        shots: int | None = None,
+        backend: BackendLike = None,
+        seed: int | None = None,
+    ) -> None:
+        if n_clusters < 1:
+            raise ValueError("n_clusters must be at least 1")
+        self.n_clusters = n_clusters
+        self.feature_map = feature_map
+        self.max_iterations = max_iterations
+        self.tol = tol
+        self.shots = shots
+        self.backend = backend
+        self.seed = seed
+        self.centroids_: npt.NDArray[Any] | None = None
+        self.labels_: npt.NDArray[Any] | None = None
+
+    # ---------------------------------------------------------------- distance --
+    def _kernel(self, n_features: int) -> QuantumKernel:
+        from qmlkit.encoding.feature_maps import AngleFeatureMap
+
+        fmap = self.feature_map or AngleFeatureMap(n_features, entangle=n_features > 1)
+        return QuantumKernel(fmap, shots=self.shots, backend=self.backend, seed=self.seed)
+
+    def distances(self, X: npt.NDArray[Any], centroids: npt.NDArray[Any]) -> npt.NDArray[Any]:
+        r"""``(n_samples, k)`` of :math:`2(1 - k(x, c))`.
+
+        A kernel with unit diagonal induces a genuine squared distance this way, so
+        the assignment step below is the ordinary one — no special-casing.
+        """
+        kernel = self._kernel(X.shape[1])
+        gram = kernel(np.asarray(X, dtype=float), np.asarray(centroids, dtype=float))
+        return 2.0 * (1.0 - gram)
+
+    # -------------------------------------------------------------------- fit --
+    def fit(self, X: npt.NDArray[Any], seed: int | None = None) -> QMeansResult:
+        data = np.asarray(X, dtype=float)
+        if len(data) < self.n_clusters:
+            raise ValueError(f"cannot form {self.n_clusters} clusters from {len(data)} samples")
+        rng = np.random.default_rng(self.seed if seed is None else seed)
+        # k-means++ style start: distinct rows, so two centroids cannot collide
+        chosen = rng.choice(len(data), size=self.n_clusters, replace=False)
+        centroids = data[chosen].copy()
+
+        history: list[float] = []
+        labels = np.zeros(len(data), dtype=int)
+        iteration = 0
+        for iteration in range(self.max_iterations):  # noqa: B007 - used after the loop
+            d = self.distances(data, centroids)
+            labels = np.argmin(d, axis=1)
+            inertia = float(d[np.arange(len(data)), labels].sum())
+            history.append(inertia)
+
+            moved = centroids.copy()
+            for k in range(self.n_clusters):
+                members = data[labels == k]
+                if len(members):
+                    moved[k] = members.mean(axis=0)
+                # An empty cluster keeps its centroid rather than drifting or
+                # collapsing onto another; duplicated points make that reachable.
+            shift = float(np.abs(moved - centroids).max())
+            centroids = moved
+            if shift < self.tol:
+                break
+
+        self.centroids_ = centroids
+        self.labels_ = labels
+        return QMeansResult(
+            labels=labels,
+            centroids=centroids,
+            inertia=history[-1],
+            n_iterations=iteration + 1,
+            history=history,
+        )
+
+    def predict(self, X: npt.NDArray[Any]) -> npt.NDArray[Any]:
+        if self.centroids_ is None:
+            raise ValueError("QMeans must be fitted before predicting")
+        return np.argmin(self.distances(np.asarray(X, dtype=float), self.centroids_), axis=1)
+
+    def fit_predict(self, X: npt.NDArray[Any], seed: int | None = None) -> npt.NDArray[Any]:
+        return self.fit(X, seed=seed).labels
+
+    def __repr__(self) -> str:
+        name = type(self.feature_map).__name__ if self.feature_map else "AngleFeatureMap"
+        return f"QMeans(n_clusters={self.n_clusters}, feature_map={name})"

qmlkit/algorithms/hamiltonians.py

@@ -0,0 +1,143 @@
+r"""Hamiltonians to hand to VQE, and an exact answer to check it against.
+
+A Hamiltonian here is just a :class:`~qmlkit.core.observables.PauliSum` — the same
+type an expectation value takes — so nothing new has to learn about it. These are
+constructors, not a new class hierarchy.
+
+:func:`exact_ground_energy` diagonalises the dense matrix. That is exponential and
+useless past ~14 qubits, which is exactly the point: it is the oracle a variational
+result gets *checked* against on small systems, not a method to compete with.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Sequence
+from typing import Any
+
+import numpy as np
+import numpy.typing as npt
+
+from qmlkit.core.builder import entangler_pairs
+from qmlkit.core.observables import Observable, PauliString, PauliSum, as_sum
+
+__all__ = [
+    "pauli_hamiltonian",
+    "ising_hamiltonian",
+    "heisenberg_hamiltonian",
+    "max_cut_hamiltonian",
+    "hamiltonian_matrix",
+    "exact_ground_energy",
+    "exact_ground_state",
+]
+
+_PAULI: dict[str, npt.NDArray[Any]] = {
+    "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 pauli_hamiltonian(terms: Iterable[tuple[str, Sequence[int], float]]) -> PauliSum:
+    """Build from ``(paulis, qubits, coefficient)`` triples.
+
+    >>> pauli_hamiltonian([("ZZ", (0, 1), 1.0), ("X", (0,), -0.5)])
+    Z0 Z1 + -0.5*X0
+    """
+    out: list[PauliString] = []
+    for letters, qubits, coeff in terms:
+        # A constant term is the identity: no letters and no qubits. Allowed, because
+        # dropping it would silently shift every energy the Hamiltonian reports.
+        if not letters and not tuple(qubits):
+            out.append(PauliString((), float(coeff)))
+            continue
+        if len(letters) != len(qubits):
+            raise ValueError(f"{letters!r} needs {len(letters)} qubits, got {tuple(qubits)}")
+        paulis = tuple(
+            (int(q), p.upper()) for q, p in zip(qubits, letters, strict=True) if p.upper() != "I"
+        )
+        out.append(PauliString(tuple(sorted(paulis)), float(coeff)))
+    return PauliSum(tuple(out))
+
+
+def ising_hamiltonian(
+    n_qubits: int,
+    j: float = 1.0,
+    h: float = 1.0,
+    edges: Sequence[tuple[int, int]] | None = None,
+    pattern: str = "chain",
+) -> PauliSum:
+    r"""Transverse-field Ising model, :math:`H = J\sum Z_iZ_j + h\sum X_i`.
+
+    The standard first test for any variational eigensolver: it is exactly solvable,
+    frustration-free at ``h=0``, and its ground state becomes genuinely entangled as
+    ``h`` grows, so a working VQE has to do real work.
+    """
+    graph = list(edges) if edges is not None else list(entangler_pairs(n_qubits, pattern))
+    terms: list[tuple[str, tuple[int, ...], float]] = [("ZZ", (a, b), j) for a, b in graph]
+    terms += [("X", (q,), h) for q in range(n_qubits)]
+    return pauli_hamiltonian(terms)
+
+
+def heisenberg_hamiltonian(
+    n_qubits: int,
+    jx: float = 1.0,
+    jy: float = 1.0,
+    jz: float = 1.0,
+    h: float = 0.0,
+    edges: Sequence[tuple[int, int]] | None = None,
+    pattern: str = "chain",
+) -> PauliSum:
+    r"""Heisenberg model, :math:`\sum J_\alpha \sigma^\alpha_i\sigma^\alpha_j + h\sum Z_i`."""
+    graph = list(edges) if edges is not None else list(entangler_pairs(n_qubits, pattern))
+    terms: list[tuple[str, Sequence[int], float]] = []
+    for a, b in graph:
+        for letter, coupling in (("XX", jx), ("YY", jy), ("ZZ", jz)):
+            if coupling:
+                terms.append((letter, (a, b), coupling))
+    terms += [("Z", (q,), h) for q in range(n_qubits) if h]
+    return pauli_hamiltonian(terms)
+
+
+def max_cut_hamiltonian(edges: Sequence[tuple[int, int]], n_qubits: int | None = None) -> PauliSum:
+    r"""MaxCut cost, :math:`\tfrac12\sum_{(i,j)\in E}(Z_iZ_j - 1)`.
+
+    Minimising this maximises the cut, and its ground-state energy is
+    ``-(number of edges cut)``. The constant is kept rather than dropped so the
+    energy VQE or QAOA reports *is* the negated cut size, with nothing to add back.
+    """
+    if not edges:
+        raise ValueError("MaxCut needs at least one edge")
+    _ = n_qubits  # width comes from the edges themselves; kept for a symmetric API
+    terms: list[tuple[str, Sequence[int], float]] = [("ZZ", (a, b), 0.5) for a, b in edges]
+    terms.append(("", (), -0.5 * len(edges)))
+    return pauli_hamiltonian(terms)
+
+
+def hamiltonian_matrix(obs: Observable, n_qubits: int) -> npt.NDArray[Any]:
+    """Dense ``2**n x 2**n`` matrix. Exponential — for checking, not for running."""
+    if n_qubits > 14:
+        raise ValueError(
+            f"a dense matrix for {n_qubits} qubits needs {4**n_qubits * 16 / 1e9:.0f} GB; "
+            "this function exists to verify small cases, not to solve large ones"
+        )
+    dim = 2**n_qubits
+    total = np.zeros((dim, dim), dtype=complex)
+    for term in as_sum(obs).terms:
+        letters = dict(term.paulis)
+        matrix = np.eye(1, dtype=complex)
+        for qubit in range(n_qubits):
+            matrix = np.kron(matrix, _PAULI[letters.get(qubit, "I")])
+        total += complex(term.coeff) * matrix
+    return total
+
+
+def exact_ground_energy(obs: Observable, n_qubits: int) -> float:
+    """Lowest eigenvalue, by dense diagonalisation. The oracle, not the method."""
+    return float(np.linalg.eigvalsh(hamiltonian_matrix(obs, n_qubits))[0])
+
+
+def exact_ground_state(obs: Observable, n_qubits: int) -> tuple[float, npt.NDArray[Any]]:
+    """Lowest eigenvalue and its eigenvector."""
+    values, vectors = np.linalg.eigh(hamiltonian_matrix(obs, n_qubits))
+    return float(values[0]), np.asarray(vectors[:, 0])