qversus 0.1.0__py3-none-any.whl

qversus/__init__.py

@@ -0,0 +1,17 @@
+"""qversus: canonical quantum-computing problems, solved by real frameworks next to classical baselines.
+
+A `Problem` is a formulation (Grover search, MaxCut, H2 ground state, a surface-code memory, ...) with a
+set of `Instance`s. A `Solver` is a thin adapter that attacks a problem with ONE real framework (Qiskit +
+Aer, PennyLane, Cirq, Stim + PyMatching) or with a classical method, and returns the same `SolverResult`
+shape whatever the framework. The registry pairs them, so putting a quantum method next to the classical
+baseline that is usually still more practical is one loop, not a per-framework script.
+
+Circuit-model solvers also return a `Trace`: a replayable, JSON-first recording of the run (the state after
+every gate, per-qubit Bloch vectors, probabilities, a seeded shot histogram). A run is a pure function of
+`(params, seed)`.
+
+The core needs NumPy only. Each framework is an optional extra; a missing framework disables only its own
+adapters. See the README and docs/ for the contracts.
+"""
+
+__version__ = "0.01.000"  # display form X.XX.XXX; pyproject.toml carries the PEP 440 form 0.1.0

qversus/core/__init__.py

@@ -0,0 +1,22 @@
+"""qversus.core, the framework-free substrate (no quantum SDK imported here).
+
+- rng:   seeded RNG and shot sampling, so a run is a pure function of (params, seed).
+- trace: the quantum trace schema (the artifact contract every circuit-model solver emits).
+
+`qversus.core.circuit_trace` (the Qiskit step tracer) is deliberately NOT imported here, so importing the
+core never requires Qiskit.
+"""
+
+from qversus.core.rng import DEFAULT_SEED, make_rng, sample_counts
+from qversus.core.trace import ROUND, SCHEMA_VERSION, Step, Trace, amp
+
+__all__ = [
+    "DEFAULT_SEED",
+    "make_rng",
+    "sample_counts",
+    "ROUND",
+    "SCHEMA_VERSION",
+    "Step",
+    "Trace",
+    "amp",
+]

qversus/core/circuit_trace.py

@@ -0,0 +1,107 @@
+"""Shared circuit→trace tracer (Qiskit). NOT imported by qversus.core.__init__, so `import qversus.core`
+stays Qiskit-free (live-thin); only the precompute solvers import this.
+
+Given a Qiskit circuit built gate-by-gate, `evolve` replays it one instruction at a time on a
+`Statevector`, recording, after every step, the full statevector, the per-qubit reduced Bloch vector,
+and the basis-state probabilities. That sequence of `Step`s IS the animation a consumer replays. Any
+circuit-model solver (Qiskit, Cirq via QASM, …) funnels through here so every framework yields the same
+trace shape, the adapter boundary the registry depends on.
+
+Qubit/index convention (documented once, used everywhere): Qiskit's native little-endian, basis index
+`i` has qubit 0 as its least-significant bit. The web renderer uses the same arrays, never reversed.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from qiskit import QuantumCircuit
+from qiskit.quantum_info import Pauli, Statevector, partial_trace
+
+from qversus.core.rng import sample_counts
+from qversus.core.trace import ROUND, Step, amp
+
+_PAULIS = ("X", "Y", "Z")
+
+
+def bloch(sv: Statevector, n: int) -> list[list[float]]:
+    """Per-qubit reduced Bloch vector [⟨X⟩, ⟨Y⟩, ⟨Z⟩] via the reduced density matrix."""
+    out: list[list[float]] = []
+    for q in range(n):
+        others = [j for j in range(n) if j != q]
+        rho = partial_trace(sv, others)
+        out.append([round(float(rho.expectation_value(Pauli(p)).real), ROUND) for p in _PAULIS])
+    return out
+
+
+def _scalar_params(params) -> list[float]:
+    """Keep only real scalar gate params (a UnitaryGate carries a matrix, not floats, skip those)."""
+    out: list[float] = []
+    for x in params or []:
+        try:
+            out.append(round(float(x), ROUND))
+        except (TypeError, ValueError):
+            pass
+    return out
+
+
+def step_of(index: int, gate: str, targets, label: dict, sv: Statevector, n: int, params=None) -> Step:
+    return Step(
+        index=index,
+        gate=gate,
+        targets=[int(t) for t in targets],
+        label=label,
+        statevector=[amp(z) for z in sv.data],
+        bloch=bloch(sv, n),
+        probabilities=[round(float(p), ROUND) for p in sv.probabilities()],
+        params=_scalar_params(params),
+    )
+
+
+def evolve(qc: QuantumCircuit, captions: list[dict] | None = None) -> list[Step]:
+    """Step-replay a circuit, returning the per-step trace (incl. an initial |0…0⟩ frame).
+
+    `captions[k]` (optional) is the bilingual label for the k-th unitary instruction (0-based).
+    """
+    n = qc.num_qubits
+    sv = Statevector.from_int(0, 2**n)
+    steps = [step_of(0, "init", [], {"en": "Initial state |0…0⟩", "es": "Estado inicial |0…0⟩"}, sv, n)]
+    k = 0
+    for inst in qc.data:
+        op = inst.operation
+        if op.name in ("measure", "barrier"):
+            continue
+        qargs = [qc.find_bit(q).index for q in inst.qubits]
+        sub = QuantumCircuit(n)
+        sub.append(op, qargs)
+        sv = sv.evolve(sub)
+        label = captions[k] if (captions and k < len(captions) and captions[k]) else {
+            "en": f"{op.name.upper()} q{qargs}",
+            "es": f"{op.name.upper()} q{qargs}",
+        }
+        steps.append(step_of(k + 1, op.name.upper(), qargs, label, sv, n, list(op.params)))
+        k += 1
+    return steps
+
+
+def circuit_ops(qc: QuantumCircuit) -> list[dict]:
+    """A flat, JSON-able op list for the diagram renderer (excludes barriers)."""
+    ops: list[dict] = []
+    for inst in qc.data:
+        op = inst.operation
+        if op.name == "barrier":
+            continue
+        ops.append(
+            {
+                "gate": op.name,
+                "targets": [qc.find_bit(q).index for q in inst.qubits],
+                "params": _scalar_params(op.params),
+            }
+        )
+    return ops
+
+
+def measure_counts(qc: QuantumCircuit, shots: int, seed: int) -> dict:
+    """Final measurement histogram, sampled deterministically from the exact final statevector."""
+    sv = Statevector.from_int(0, 2**qc.num_qubits).evolve(qc)
+    counts = sample_counts(np.asarray(sv.probabilities()), shots=shots, seed=seed)
+    return {"counts": counts, "shots": shots}

qversus/core/rng.py

@@ -0,0 +1,38 @@
+"""Seeded RNG. A qversus run is a pure function of (params, seed): same seed → byte-identical trace.
+
+Measurement sampling (shot histograms) is the only stochastic step in the pipeline; everything else
+(statevector evolution) is deterministic. We route all sampling through one seeded NumPy Generator so the
+committed counts reproduce exactly.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+DEFAULT_SEED = 42
+
+
+def make_rng(seed: int = DEFAULT_SEED) -> np.random.Generator:
+    """Return a NumPy Generator seeded deterministically (PCG64)."""
+    return np.random.default_rng(seed)
+
+
+def sample_counts(probabilities: np.ndarray, shots: int, seed: int = DEFAULT_SEED) -> dict[str, int]:
+    """Sample `shots` measurements from a probability vector over 2**n basis states.
+
+    Returns a {bitstring: count} dict, omitting zero counts. Each key is the basis index written in binary,
+    most significant bit first: the HIGHEST qubit is leftmost and qubit 0 is the rightmost character (Qiskit's
+    little-endian convention, the same order as `format(index, f"0{n}b")`).
+    """
+    n_states = len(probabilities)
+    n_qubits = int(np.log2(n_states))
+    rng = make_rng(seed)
+    # Guard against tiny negative/round-off so np.random.choice accepts the vector.
+    p = np.clip(np.asarray(probabilities, dtype=float), 0.0, None)
+    p = p / p.sum()
+    draws = rng.choice(n_states, size=shots, p=p)
+    counts: dict[str, int] = {}
+    for idx, c in zip(*np.unique(draws, return_counts=True)):
+        bitstring = format(int(idx), f"0{n_qubits}b")
+        counts[bitstring] = int(c)
+    return dict(sorted(counts.items()))

qversus/core/trace.py

@@ -0,0 +1,69 @@
+"""The quantum trace schema: the artifact contract between the engine and whatever consumes its runs.
+
+A trace is a *replayable recording* of one circuit run: for every step (one gate / a barrier / a
+measurement) we store the full statevector, the per-qubit Bloch vector, and the basis-state
+probabilities, plus the final measurement histogram. A consumer (a notebook, a report, a static web app)
+only reads or animates it: replay is the truth, nothing is recomputed. The schema is JSON-first, compact,
+and free of any framework type, so a reader never needs Python or a quantum SDK to use it.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+
+SCHEMA_VERSION = "qversus-trace/1"
+
+# Amplitudes/Bloch coords are rounded to keep traces small and gzip-friendly; 6 decimals is well below
+# any didactic precision need and keeps |state| ~ 1 to float tolerance.
+ROUND = 6
+
+
+def amp(z: complex) -> dict[str, float]:
+    """Serialize a complex amplitude as {"re", "im"} rounded for compactness."""
+    return {"re": round(float(z.real), ROUND), "im": round(float(z.imag), ROUND)}
+
+
+@dataclass
+class Step:
+    """One animation frame: the state immediately AFTER applying `gate`."""
+
+    index: int
+    gate: str                       # e.g. "H", "CX", "RY", "barrier", "measure"
+    targets: list[int]              # qubit indices the gate acts on
+    label: dict[str, str]           # bilingual short caption {"en":..., "es":...}
+    statevector: list[dict[str, float]]   # 2**n amplitudes as {"re","im"}
+    bloch: list[list[float]]        # per-qubit reduced Bloch vector [x, y, z]
+    probabilities: list[float]      # 2**n basis-state probabilities
+    params: list[float] = field(default_factory=list)
+
+
+@dataclass
+class Trace:
+    """A complete, replayable case run."""
+
+    case_id: str
+    title: dict[str, str]           # bilingual {"en","es"}
+    concept: dict[str, str]         # bilingual one-paragraph "what this teaches"
+    qubits: int
+    steps: list[Step]
+    measurements: dict              # {"counts": {bitstring: int}, "shots": int}
+    circuit_ops: list[dict]         # flat op list for the diagram renderer
+    provenance: dict                # {engine, engine_version, seed, lane, ran_on}
+    references: list[dict] = field(default_factory=list)   # [{"label","doi"|"url"}]
+    extra: dict = field(default_factory=dict)              # optional noisy/mitigated/curves blocks
+    schema_version: str = SCHEMA_VERSION
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+    def write_json(self, path: str | Path) -> Path:
+        path = Path(path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        # Bytes, not text: write_text turns "\n" into CRLF on Windows, so a run's bytes would depend on the OS.
+        path.write_bytes(json.dumps(self.to_dict(), indent=1, ensure_ascii=False).encode("utf-8"))
+        return path
+
+    def nbytes(self) -> int:
+        return len(json.dumps(self.to_dict(), ensure_ascii=False).encode("utf-8"))

qversus/problems/__init__.py

@@ -0,0 +1,30 @@
+"""Problem catalog. Importing this package registers every problem (one import line per module).
+Adding a problem = add its module here; nothing else changes.
+"""
+
+from qversus.problems import (  # noqa: F401  (import = registration)
+    bernstein_vazirani,
+    chsh,
+    deutsch_jozsa,
+    grover,
+    interference,
+    maxcut,
+    noise,
+    qec_repetition,
+    qec_surface,
+    qft,
+    qml_classifier,
+    qpe,
+    qrng,
+    shor,
+    simon,
+    single_qubit,
+    state_prep,
+    superdense,
+    teleportation,
+    vqe,
+)
+
+__all__ = ["state_prep", "maxcut", "bernstein_vazirani", "deutsch_jozsa", "simon", "grover", "qft", "qpe",
+           "shor", "vqe", "qml_classifier", "noise", "qec_repetition", "qec_surface", "chsh", "teleportation",
+           "superdense", "single_qubit", "qrng", "interference"]

qversus/problems/base.py

@@ -0,0 +1,51 @@
+"""Problem formulations, what to compute, independent of the method that computes it.
+
+A `Problem` declares its didactic identity (bilingual title/concept, category) and its set of
+`Instance`s (the variant regimes a consumer can select between; aim for ≥6 where a meaningful
+parametric family exists). It is solver-agnostic: the same problem is attacked by many `Solver`s
+(quantum + classical), each a thin adapter over a real framework. Adding a problem never touches a solver.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Instance:
+    """One variant regime of a problem (a full parameter vector a consumer can select)."""
+
+    id: str
+    title: dict[str, str]            # bilingual short label for the variant chip
+    params: dict                     # problem-specific (graph edges, geometry, marked item, N, …)
+    note: dict[str, str] = field(default_factory=dict)   # bilingual "what this regime shows"
+
+
+class Problem(ABC):
+    """A formulation. Concrete problems set the class attributes and implement `instances`."""
+
+    id: str = "problem"
+    title: dict[str, str] = {"en": "Problem", "es": "Problema"}
+    concept: dict[str, str] = {"en": "", "es": ""}
+    category: str = "fundamentals"
+    # The bilingual name of the quantity the solvers compute (energy, max cut, found item, …).
+    metric: dict[str, str] = {"en": "result", "es": "resultado"}
+    references: list[dict] = []      # [{label, doi|url}] shared by the case
+    # Is the circuit small and clean enough to re-simulate interactively (e.g. in a browser)? False when the case needs an offline-only
+    # feature (optimization loop, realistic noise, mid-circuit feed-forward, >12 qubits). The gate still
+    # re-checks the measured numbers; this is the case author's honest hint.
+    live_capable: bool = True
+
+    @abstractmethod
+    def instances(self) -> list[Instance]:
+        """The variant regimes (≥6 where a parametric family exists; a single honest benchmark otherwise)."""
+
+    def instance(self, instance_id: str | None) -> Instance:
+        items = self.instances()
+        if instance_id is None:
+            return items[0]
+        for it in items:
+            if it.id == instance_id:
+                return it
+        raise KeyError(f"{self.id}: no instance {instance_id!r} (have {[i.id for i in items]})")

qversus/problems/bernstein_vazirani.py

@@ -0,0 +1,70 @@
+"""Bernstein–Vazirani, recover a hidden bit-string from an oracle.
+
+Given an oracle f(x) = s·x (mod 2) for a hidden string s, the Bernstein–Vazirani algorithm recovers s with
+a SINGLE quantum oracle query via phase kickback + interference, where any classical algorithm needs n
+queries (one per bit). It is the cleanest demonstration of a genuine, if oracle-model, quantum query
+advantage. The honest nuance (the comparison panel makes it explicit): the advantage is in *query count*,
+not wall-clock; at these sizes a classical computer answers instantly.
+"""
+
+from __future__ import annotations
+
+from qversus.problems.base import Instance, Problem
+from qversus.registry import register_problem
+
+
+@register_problem
+class BernsteinVazirani(Problem):
+    id = "bernstein-vazirani"
+    category = "oracle-algorithms"
+    live_capable = True
+    title = {"en": "Bernstein–Vazirani, 1 query vs n", "es": "Bernstein–Vazirani, 1 consulta vs n"}
+    concept = {
+        "en": (
+            "A hidden string s is encoded in an oracle f(x) = s·x mod 2. Bernstein–Vazirani puts the input "
+            "register in uniform superposition, the answer qubit in |−⟩, queries the oracle once, phase "
+            "kickback stamps (−1)^{s·x} onto each branch, and a final layer of Hadamards interferes the "
+            "branches so that measuring the input register yields s exactly. Classically you must query the "
+            "oracle n times (once per bit). One quantum query vs n classical queries."
+        ),
+        "es": (
+            "Una cadena oculta s se codifica en un oráculo f(x) = s·x mod 2. Bernstein–Vazirani pone el "
+            "registro de entrada en superposición uniforme, el qubit de respuesta en |−⟩, consulta el "
+            "oráculo una vez, el phase kickback marca (−1)^{s·x} en cada rama, y una capa final de "
+            "Hadamards interfiere las ramas de modo que medir el registro de entrada da s exactamente. "
+            "Clásicamente hay que consultar el oráculo n veces (una por bit). Una consulta cuántica vs n."
+        ),
+    }
+    metric = {"en": "recovered hidden string", "es": "cadena oculta recuperada"}
+    references = [
+        {"label": "Bernstein & Vazirani, Quantum complexity theory, SIAM J. Comput. 26(5) (1997)",
+         "doi": "10.1137/S0097539796300921"},
+        {"label": "Nielsen & Chuang, Quantum Computation and Quantum Information (2010)",
+         "url": "https://doi.org/10.1017/CBO9780511976667"},
+    ]
+
+    @staticmethod
+    def oracle(secret: str, x: int) -> int:
+        """f(x) = parity of (secret AND x), the classically queryable oracle. `secret[i]` is bit of qubit i."""
+        n = len(secret)
+        bits = [(x >> i) & 1 for i in range(n)]            # bit i of x ↔ qubit i
+        return sum(int(secret[i]) & bits[i] for i in range(n)) % 2
+
+    def instances(self) -> list[Instance]:
+        secrets = [
+            ("101", "bv-101"),
+            ("0111", "bv-0111"),
+            ("1101", "bv-1101"),
+            ("11010", "bv-11010"),
+            ("101101", "bv-101101"),
+            ("111111", "bv-111111"),
+        ]
+        out = []
+        for s, iid in secrets:
+            out.append(Instance(
+                iid, {"en": f"s = {s}", "es": f"s = {s}"},
+                {"n": len(s), "secret": s},
+                {"en": f"Hidden string {s} ({len(s)} bits), recovered in 1 query vs {len(s)} classical.",
+                 "es": f"Cadena oculta {s} ({len(s)} bits), recuperada en 1 consulta vs {len(s)} clásicas."},
+            ))
+        return out

qversus/problems/chsh.py

@@ -0,0 +1,74 @@
+"""CHSH / Bell inequality, where quantum GENUINELY beats classical (and where it doesn't).
+
+Two parties share an entangled pair and each measures in one of two settings. The CHSH correlator
+S = E(a₀,b₀) + E(a₀,b₁) + E(a₁,b₀) − E(a₁,b₁) is bounded by |S| ≤ 2 for ANY local-hidden-variable
+(classical) theory, but quantum mechanics reaches the Tsirelson bound |S| = 2√2 ≈ 2.83 with the right
+angles on a Bell state. qversus computes S from the real quantum state across several angle settings. This is
+the rare, honest case where quantum *does* beat classical, but it is a **nonlocality** advantage (ruling
+out local realism; the basis of the 2022 Nobel Prize), NOT a computational speedup. It also shows the
+necessary ingredient: a separable (unentangled) state cannot violate the bound.
+"""
+
+from __future__ import annotations
+
+import math
+
+from qversus.problems.base import Instance, Problem
+from qversus.registry import register_problem
+
+PI = math.pi
+
+
+@register_problem
+class CHSH(Problem):
+    id = "chsh"
+    category = "entanglement"
+    live_capable = True
+    title = {"en": "CHSH / Bell inequality", "es": "Desigualdad CHSH / Bell"}
+    concept = {
+        "en": (
+            "Share a Bell pair; Alice measures at angle a₀ or a₁, Bob at b₀ or b₁. The CHSH quantity "
+            "S = E(a₀,b₀)+E(a₀,b₁)+E(a₁,b₀)−E(a₁,b₁) cannot exceed 2 for any classical (local-hidden-"
+            "variable) theory, yet a Bell state with optimal angles reaches the Tsirelson bound 2√2 ≈ 2.83. "
+            "Violating |S|≤2 rules out local realism, a real, experimentally confirmed quantum effect (2022 "
+            "Nobel). But it is a foundational/nonlocality advantage, not a faster computation; and a "
+            "separable state cannot violate the bound at all, so entanglement is the necessary ingredient."
+        ),
+        "es": (
+            "Comparte un par de Bell; Alice mide en ángulo a₀ o a₁, Bob en b₀ o b₁. La cantidad CHSH "
+            "S = E(a₀,b₀)+E(a₀,b₁)+E(a₁,b₀)−E(a₁,b₁) no puede superar 2 en ninguna teoría clásica (de "
+            "variables ocultas locales), pero un estado de Bell con ángulos óptimos alcanza la cota de "
+            "Tsirelson 2√2 ≈ 2.83. Violar |S|≤2 descarta el realismo local, un efecto cuántico real y "
+            "confirmado experimentalmente (Nobel 2022). Pero es una ventaja fundacional/de no-localidad, no "
+            "un cálculo más rápido; y un estado separable no puede violar la cota, así que el entrelazamiento "
+            "es el ingrediente necesario."
+        ),
+    }
+    metric = {"en": "CHSH value S (classical ≤ 2, quantum ≤ 2√2)", "es": "valor CHSH S (clásico ≤ 2, cuántico ≤ 2√2)"}
+    references = [
+        {"label": "Clauser, Horne, Shimony & Holt, Proposed experiment to test local hidden-variable theories (1969)",
+         "doi": "10.1103/PhysRevLett.23.880"},
+        {"label": "Aspect, Nobel Prize in Physics 2022, Bell inequality experiments",
+         "url": "https://www.nobelprize.org/prizes/physics/2022/summary/"},
+    ]
+
+    def instances(self) -> list[Instance]:
+        # angles (a0, a1, b0, b1) in radians; `entangled` toggles Bell vs product state.
+        opt = (0.0, PI / 2, PI / 4, -PI / 4)
+        defs = [
+            ("chsh-optimal", "Bell, optimal angles → 2√2", opt, True),
+            ("chsh-suboptimal", "Bell, sub-optimal angles", (0.0, PI / 2, PI / 6, -PI / 6), True),
+            ("chsh-weak", "Bell, weak angles", (0.0, PI / 3, PI / 8, -PI / 8), True),
+            ("chsh-aligned", "Bell, aligned bases → S=2", (0.0, 0.0, 0.0, PI / 2), True),
+            ("chsh-rotated", "Bell, rotated optimal (still 2√2)", (PI / 8, PI / 8 + PI / 2, PI / 8 + PI / 4, PI / 8 - PI / 4), True),
+            ("chsh-product", "Separable state (no entanglement)", opt, False),
+        ]
+        out = []
+        for iid, label, angles, ent in defs:
+            out.append(Instance(
+                iid, {"en": label, "es": label},
+                {"n": 2, "a0": angles[0], "a1": angles[1], "b0": angles[2], "b1": angles[3], "entangled": ent},
+                {"en": f"{'Bell pair' if ent else 'product state'}, see whether S exceeds the classical 2.",
+                 "es": f"{'par de Bell' if ent else 'estado producto'}, muestra si S supera el clásico 2."},
+            ))
+        return out

qversus/problems/deutsch_jozsa.py

@@ -0,0 +1,75 @@
+"""Deutsch–Jozsa, decide constant vs balanced in one query.
+
+Promised that f:{0,1}^n→{0,1} is either constant (same output for all inputs) or balanced (0 on exactly
+half the inputs), Deutsch–Jozsa decides which with a SINGLE quantum oracle query. Deterministically,
+classically you may need 2^{n-1}+1 queries (just over half the inputs) to be certain, an exponential
+query-complexity gap. The honest nuance (the comparison panel says it): it is an oracle-model, query-count
+advantage; at these sizes the classical decision is still instant.
+"""
+
+from __future__ import annotations
+
+from qversus.problems.base import Instance, Problem
+from qversus.registry import register_problem
+
+
+@register_problem
+class DeutschJozsa(Problem):
+    id = "deutsch-jozsa"
+    category = "oracle-algorithms"
+    live_capable = True
+    title = {"en": "Deutsch–Jozsa, constant vs balanced", "es": "Deutsch–Jozsa, constante vs balanceada"}
+    concept = {
+        "en": (
+            "An oracle hides a function f that is promised constant or balanced. Deutsch–Jozsa puts the "
+            "input register in uniform superposition with the answer qubit in |−⟩, queries the oracle once "
+            "(phase kickback stamps (−1)^{f(x)}), and a final layer of Hadamards interferes the branches: "
+            "the input register collapses to all-zeros iff f is constant, and to something non-zero iff f "
+            "is balanced. One quantum query decides it; a deterministic classical algorithm may need "
+            "2^{n-1}+1."
+        ),
+        "es": (
+            "Un oráculo oculta una función f que se promete constante o balanceada. Deutsch–Jozsa pone el "
+            "registro de entrada en superposición uniforme con el qubit de respuesta en |−⟩, consulta el "
+            "oráculo una vez (el phase kickback marca (−1)^{f(x)}), y una capa final de Hadamards interfiere "
+            "las ramas: el registro de entrada colapsa a todo-ceros si f es constante, y a algo no nulo si f "
+            "es balanceada. Una consulta cuántica lo decide; un algoritmo clásico determinista puede "
+            "necesitar 2^{n-1}+1."
+        ),
+    }
+    metric = {"en": "constant-or-balanced verdict", "es": "veredicto constante-o-balanceada"}
+    references = [
+        {"label": "Deutsch & Jozsa, Rapid solution of problems by quantum computation, Proc. R. Soc. A 439 (1992)",
+         "doi": "10.1098/rspa.1992.0167"},
+        {"label": "Nielsen & Chuang, Quantum Computation and Quantum Information (2010)",
+         "url": "https://doi.org/10.1017/CBO9780511976667"},
+    ]
+
+    @staticmethod
+    def evaluate(params: dict, x: int) -> int:
+        """The oracle f(x). constant → fixed value; balanced → parity of (secret AND x), secret ≠ 0."""
+        if params["kind"] == "constant":
+            return params["value"]
+        n, s = params["n"], params["secret"]
+        bits = [(x >> i) & 1 for i in range(n)]
+        return sum(int(s[i]) & bits[i] for i in range(n)) % 2
+
+    def instances(self) -> list[Instance]:
+        defs = [
+            ("dj-const0-3", "constant f=0 (n=3)", {"n": 3, "kind": "constant", "value": 0}),
+            ("dj-const1-3", "constant f=1 (n=3)", {"n": 3, "kind": "constant", "value": 1}),
+            ("dj-bal-101", "balanced s=101 (n=3)", {"n": 3, "kind": "balanced", "secret": "101"}),
+            ("dj-bal-parity", "balanced full parity (n=3)", {"n": 3, "kind": "balanced", "secret": "111"}),
+            ("dj-const0-4", "constant f=0 (n=4)", {"n": 4, "kind": "constant", "value": 0}),
+            ("dj-bal-1011", "balanced s=1011 (n=4)", {"n": 4, "kind": "balanced", "secret": "1011"}),
+        ]
+        out = []
+        for iid, label, params in defs:
+            kind = "constant" if params["kind"] == "constant" else "balanced"
+            worst = 2 ** (params["n"] - 1) + 1
+            out.append(Instance(
+                iid, {"en": label, "es": label}, params,
+                {"en": f"f is {kind}, 1 quantum query vs up to {worst} classical (worst case).",
+                 "es": f"f es {kind}, 1 consulta cuántica vs hasta {worst} clásicas (peor caso)."},
+            ))
+        return out

qversus/problems/grover.py

@@ -0,0 +1,65 @@
+"""Grover's search, amplitude amplification over an unstructured database.
+
+Find a marked item in an unstructured set of N = 2ⁿ items. Grover needs ~(π/4)√(N/M) oracle queries
+(M = number of marked items) vs the classical ~N/2. The famous quadratic speedup, but honestly: it is
+*quadratic, asymptotic*, and at the tiny n a laptop simulates exactly, the classical scan still wins on
+wall-time. What it teaches beautifully is amplitude amplification: each iteration tips probability toward
+the marked state, and over-rotating (too many iterations) tips it back.
+"""
+
+from __future__ import annotations
+
+from qversus.problems.base import Instance, Problem
+from qversus.registry import register_problem
+
+
+@register_problem
+class Grover(Problem):
+    id = "grover"
+    category = "flagship-algorithms"
+    live_capable = True
+    title = {"en": "Grover, unstructured search", "es": "Grover, búsqueda no estructurada"}
+    concept = {
+        "en": (
+            "Grover searches N = 2ⁿ unstructured items for the M marked ones. Start in uniform "
+            "superposition; each Grover iteration applies the oracle (a phase flip on the marked states) "
+            "then the diffuser (inversion about the mean), rotating amplitude toward the marked subspace. "
+            "After ~(π/4)√(N/M) iterations a measurement returns a marked item with high probability, a "
+            "quadratic speedup over the classical ~N/2 scan. Run too many iterations and you *over-rotate* "
+            "past the target."
+        ),
+        "es": (
+            "Grover busca entre N = 2ⁿ ítems no estructurados los M marcados. Parte en superposición "
+            "uniforme; cada iteración de Grover aplica el oráculo (un cambio de fase en los estados "
+            "marcados) y luego el difusor (inversión respecto a la media), rotando la amplitud hacia el "
+            "subespacio marcado. Tras ~(π/4)√(N/M) iteraciones una medición devuelve un ítem marcado con "
+            "alta probabilidad, un speedup cuadrático sobre el barrido clásico ~N/2. Con demasiadas "
+            "iteraciones te *pasas* del objetivo (sobre-rotación)."
+        ),
+    }
+    metric = {"en": "marked item found", "es": "ítem marcado encontrado"}
+    references = [
+        {"label": "Grover, A fast quantum mechanical algorithm for database search, STOC '96 (1996)",
+         "doi": "10.1145/237814.237866"},
+        {"label": "Nielsen & Chuang, Quantum Computation and Quantum Information (2010)",
+         "url": "https://doi.org/10.1017/CBO9780511976667"},
+    ]
+
+    def instances(self) -> list[Instance]:
+        defs = [
+            ("grover-2-3", "n=2, mark |11⟩", {"n": 2, "marked": [3]}),
+            ("grover-3-5", "n=3, mark |101⟩", {"n": 3, "marked": [5]}),
+            ("grover-3-2", "n=3, mark |010⟩", {"n": 3, "marked": [2]}),
+            ("grover-3-2marked", "n=3, mark |011⟩,|101⟩", {"n": 3, "marked": [3, 5]}),
+            ("grover-4-10", "n=4, mark |1010⟩", {"n": 4, "marked": [10]}),
+            ("grover-4-0", "n=4, mark |0000⟩", {"n": 4, "marked": [0]}),
+        ]
+        out = []
+        for iid, label, params in defs:
+            n, m = params["n"], len(params["marked"])
+            out.append(Instance(
+                iid, {"en": label, "es": label}, params,
+                {"en": f"N={2 ** n}, M={m} marked, quantum ~(π/4)√(N/M) queries vs classical ~N/2.",
+                 "es": f"N={2 ** n}, M={m} marcados, cuántico ~(π/4)√(N/M) consultas vs clásico ~N/2."},
+            ))
+        return out