qang 0.4.0__py3-none-any.whl

qang/__init__.py

@@ -0,0 +1,43 @@
+"""
+qang — A Unified Angular-Probability Unit for Parametric Quantum Circuit Design.
+
+Reference implementation for:
+    V. H. Monteverde, "The Qang (qg): A Unified Angular-Probability Unit and
+    Metric for Parametric Quantum Circuit Design." ORCID: 0000-0001-8884-4811
+    https://doi.org/10.5281/zenodo.22832150
+
+This package covers, in order:
+  - qang.core        the qg_Z / qg_S unit exactly as defined in the paper
+                      (Section 2), plus the full Bloch-sphere (theta, phi)
+                      representation consolidated from the author's
+                      exploratory notebook.
+  - qang.gradients    the coordinate-singularity limitation from Section 4.1,
+                       a regularized alternative, and a toy VQE benchmark
+                       comparing theta-space vs qg-space optimization
+                       (Future Research Direction #3).
+  - qang.mixed        generalization to mixed states and POVMs
+                       (Future Research Direction #4, part 1).
+  - qang.multiqubit   generalization to multi-qubit tensor-product
+                       projection profiles (Future Research Direction #4,
+                       part 2).
+  - qang.qiskit_gate  qg as a native single-qubit gate for Qiskit
+                       (Future Research Direction #1). Optional: only
+                       importable if qiskit is installed.
+  - qang.cirq_gate    the same for Cirq (optional: needs cirq).
+  - qang.statistics   shot-noise error propagation theta <-> qg, and
+                       few-shot qg_Z intervals (Haar-prior Bayes, Wilson).
+  - qang.phase        the qg_Phi phase unit.
+  - qang.transformations  closed-form transition probabilities.
+  - qang.knitting     the sampling cost of circuit cutting in qg units.
+  - qang.circuits, qang.ansatze, qang.qec, qang.algorithms
+                       Qiskit circuit builders, variational ansatze, the
+                       3-qubit bit-flip code, and textbook algorithms
+                       (optional: need qiskit).
+
+See RESEARCH_NOTES.md for the derivations and results behind each module.
+"""
+
+from .core import Qang, MILLIQANG_PER_QANG
+
+__all__ = ["Qang", "MILLIQANG_PER_QANG"]
+__version__ = "0.4.0"

qang/algorithms.py

@@ -0,0 +1,310 @@
+"""
+qang.algorithms -- textbook multi-qubit quantum algorithms built with
+Qiskit, using the same "everything unitary, verify by exact statevector"
+discipline already used throughout qang (qang.qec's deferred-measurement
+error correction; qang.circuits' state constructors).
+
+Three algorithms live here:
+
+  1. Quantum teleportation, using the deferred-measurement principle:
+     the textbook version measures the Bell pair and applies classically
+     -controlled X/Z corrections, but any measure-then-classically-
+     -control circuit has an exactly equivalent fully unitary circuit
+     where the "would-be" classical controls are replaced by ordinary
+     quantum-controlled gates (Nielsen & Chuang, Section 4.4). That lets
+     correctness be checked by exact statevector fidelity instead of by
+     sampling -- the same technique qang.qec already relies on.
+
+  2. Superdense coding -- the "reverse" protocol, sending two classical
+     bits over one qubit given a pre-shared Bell pair. Empirically
+     important note (verified numerically, not assumed): with the gate
+     ordering used here, the decoded bit on qubit 0 recovers the
+     original *bit_z* (the Z-correction bit) and the decoded bit on
+     qubit 1 recovers the original *bit_x* (the X-correction bit) -- the
+     roles are swapped relative to a same-index guess, which is why the
+     variable names below say ``bit_z``/``bit_x`` rather than ``b0``/``b1``.
+
+  3. Grover's algorithm, with an oracle built from an X-sandwich plus a
+     phase-kickback multi-controlled-Z (via an H-sandwiched MCXGate) and
+     the standard diffusion operator, run for the optimal number of
+     iterations (round(pi/4 * sqrt(2**n_qubits))).
+
+This module is optional: importing ``qang`` itself never requires Qiskit.
+Only importing *this* module does, and it raises a clear, actionable error
+if Qiskit is not installed (same pattern as qang.qiskit_gate / qang.circuits).
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Tuple
+
+try:
+    from qiskit import QuantumCircuit
+    from qiskit.circuit.library import MCXGate
+    from qiskit.quantum_info import Statevector, partial_trace, state_fidelity
+
+    _QISKIT_AVAILABLE = True
+except ImportError:  # pragma: no cover - exercised only when qiskit is absent
+    _QISKIT_AVAILABLE = False
+
+
+def _require_qiskit():
+    if not _QISKIT_AVAILABLE:
+        raise ImportError(
+            "qang.algorithms requires Qiskit. Install it with "
+            "`pip install qiskit` (and, to run circuits, `pip install qiskit-aer`)."
+        )
+
+
+# --------------------------------------------------------------------- #
+# 1. Quantum teleportation (deferred-measurement / fully unitary form)
+# --------------------------------------------------------------------- #
+def teleportation_circuit(state_prep_angles: Tuple[float, float] = (0.0, 0.0)) -> "QuantumCircuit":
+    """
+    3-qubit teleportation circuit using the deferred-measurement
+    principle (no mid-circuit measurement or classical control at all):
+
+      qubit 0: Alice's message qubit, prepared via RY(theta) then RZ(phi)
+               from ``state_prep_angles`` = (theta, phi).
+      qubit 1: Alice's half of a shared Bell pair.
+      qubit 2: Bob's half of the shared Bell pair -- ends up holding an
+               exact copy of qubit 0's original state.
+
+    Bell-pair prep (H + CX on 1,2), "Bell measurement" on qubits 0,1
+    replaced by CX(0,1) + H(0) (unitary, undoes the measurement basis
+    change instead of measuring in it), and the classically-controlled
+    corrections replaced by quantum-controlled gates: CX(1, 2) and
+    CZ(0, 2). Because every step is unitary, the output state's reduced
+    density matrix on qubit 2 is *exactly* equal to the input state on
+    qubit 0 (verified via partial_trace + state_fidelity in
+    tests/test_algorithms.py, not by sampling).
+    """
+    _require_qiskit()
+    theta, phi = state_prep_angles
+    qc = QuantumCircuit(3, name="teleportation")
+    qc.ry(theta, 0)
+    qc.rz(phi, 0)
+
+    qc.h(1)
+    qc.cx(1, 2)
+
+    qc.cx(0, 1)
+    qc.h(0)
+
+    qc.cx(1, 2)
+    qc.cz(0, 2)
+    return qc
+
+
+def teleportation_output_fidelity(state_prep_angles: Tuple[float, float] = (0.0, 0.0)) -> float:
+    """
+    Build the teleportation circuit, and return the exact state fidelity
+    between qubit 2's final reduced state and qubit 0's originally
+    prepared (RY, RZ) single-qubit state. Should be 1.0 (up to floating
+    -point error) for any angles.
+    """
+    _require_qiskit()
+    theta, phi = state_prep_angles
+    original = QuantumCircuit(1)
+    original.ry(theta, 0)
+    original.rz(phi, 0)
+    original_state = Statevector.from_instruction(original)
+
+    qc = teleportation_circuit(state_prep_angles)
+    full_state = Statevector.from_instruction(qc)
+    # qubit 2 is Qiskit index 2; trace out qubits 0 and 1.
+    bob_state = partial_trace(full_state, [0, 1])
+    return float(state_fidelity(original_state, bob_state))
+
+
+# --------------------------------------------------------------------- #
+# 2. Superdense coding
+# --------------------------------------------------------------------- #
+def superdense_coding_circuit(bit_z: int, bit_x: int) -> "QuantumCircuit":
+    """
+    2-qubit superdense coding circuit encoding two classical bits
+    (``bit_z``, ``bit_x``) into one shared Bell pair using only local
+    operations on qubit 0, then decoding via CX(0,1) + H(0).
+
+    Gate sequence: H(0); CX(0,1) [shared Bell pair]; Z(0) if bit_z;
+    X(0) if bit_x; CX(0,1); H(0).
+
+    IMPORTANT (empirically verified, not a naming guess): after
+    decoding, qubit 0's computational-basis value equals the original
+    ``bit_z``, and qubit 1's value equals the original ``bit_x`` -- the
+    roles are swapped relative to same-index qubit/bit correspondence.
+    See ``decode_superdense_coding`` and tests/test_algorithms.py, which
+    check exactly this mapping for all four two-bit messages.
+    """
+    _require_qiskit()
+    if bit_z not in (0, 1) or bit_x not in (0, 1):
+        raise ValueError(f"bit_z and bit_x must each be 0 or 1, got bit_z={bit_z}, bit_x={bit_x}.")
+
+    qc = QuantumCircuit(2, name=f"superdense_{bit_z}{bit_x}")
+    qc.h(0)
+    qc.cx(0, 1)
+
+    if bit_z == 1:
+        qc.z(0)
+    if bit_x == 1:
+        qc.x(0)
+
+    qc.cx(0, 1)
+    qc.h(0)
+    return qc
+
+
+def decode_superdense_coding(qc: "QuantumCircuit") -> Tuple[int, int]:
+    """
+    Deterministically decode a superdense-coding circuit's output
+    (exact statevector, no sampling): returns (bit_z, bit_x) as read off
+    qubit 0 and qubit 1's individual (deterministic, 0/1-probability)
+    marginals respectively.
+    """
+    _require_qiskit()
+    sv = Statevector.from_instruction(qc)
+    probs_q0 = sv.probabilities(qargs=[0])
+    probs_q1 = sv.probabilities(qargs=[1])
+    bit_z = int(round(probs_q0[1]))
+    bit_x = int(round(probs_q1[1]))
+    return bit_z, bit_x
+
+
+# --------------------------------------------------------------------- #
+# 3. Grover's algorithm
+# --------------------------------------------------------------------- #
+def grover_oracle(n_qubits: int, marked_state: int) -> "QuantumCircuit":
+    """
+    Phase oracle that flips the sign of exactly |marked_state> (an
+    integer in [0, 2**n_qubits)), via the standard X-sandwich + phase
+    -kickback multi-controlled-Z trick: flip every qubit whose bit in
+    ``marked_state`` is 0, apply a multi-controlled Z (built from an
+    H-sandwiched MCXGate on an ancilla-free all-controls-are-qubits
+    version using phase kickback on the last qubit), then undo the
+    X-sandwich.
+    """
+    _require_qiskit()
+    if n_qubits < 1:
+        raise ValueError(f"n_qubits must be >= 1, got {n_qubits}.")
+    if not (0 <= marked_state < 2 ** n_qubits):
+        raise ValueError(f"marked_state must be in [0, 2**n_qubits), got {marked_state}.")
+
+    qc = QuantumCircuit(n_qubits, name=f"oracle_{marked_state}")
+    bits = [(marked_state >> i) & 1 for i in range(n_qubits)]  # bits[i] = qubit i's target bit
+
+    for i, b in enumerate(bits):
+        if b == 0:
+            qc.x(i)
+
+    if n_qubits == 1:
+        qc.z(0)
+    else:
+        qc.h(n_qubits - 1)
+        qc.append(MCXGate(n_qubits - 1), list(range(n_qubits - 1)) + [n_qubits - 1])
+        qc.h(n_qubits - 1)
+
+    for i, b in enumerate(bits):
+        if b == 0:
+            qc.x(i)
+    return qc
+
+
+def grover_diffusion(n_qubits: int) -> "QuantumCircuit":
+    """
+    Standard Grover diffusion operator (inversion about the mean):
+    H^{\\otimes n}; X^{\\otimes n}; multi-controlled-Z (phase kickback,
+    same construction as grover_oracle); X^{\\otimes n}; H^{\\otimes n}.
+    """
+    _require_qiskit()
+    if n_qubits < 1:
+        raise ValueError(f"n_qubits must be >= 1, got {n_qubits}.")
+
+    qc = QuantumCircuit(n_qubits, name="diffusion")
+    for q in range(n_qubits):
+        qc.h(q)
+    for q in range(n_qubits):
+        qc.x(q)
+
+    if n_qubits == 1:
+        qc.z(0)
+    else:
+        qc.h(n_qubits - 1)
+        qc.append(MCXGate(n_qubits - 1), list(range(n_qubits - 1)) + [n_qubits - 1])
+        qc.h(n_qubits - 1)
+
+    for q in range(n_qubits):
+        qc.x(q)
+    for q in range(n_qubits):
+        qc.h(q)
+    return qc
+
+
+def grover_optimal_iterations(n_qubits: int) -> int:
+    """round(pi/4 * sqrt(2**n_qubits)), the standard optimal number of
+    Grover iterations for a single marked item among 2**n_qubits."""
+    if n_qubits < 1:
+        raise ValueError(f"n_qubits must be >= 1, got {n_qubits}.")
+    return round((math.pi / 4.0) * math.sqrt(2 ** n_qubits))
+
+
+def grover_circuit(n_qubits: int, marked_state: int, n_iterations: int = None) -> "QuantumCircuit":
+    """
+    Full Grover search circuit: uniform superposition (H^{\\otimes n}),
+    then ``n_iterations`` repetitions of (oracle, diffusion).
+    ``n_iterations`` defaults to ``grover_optimal_iterations(n_qubits)``.
+    """
+    _require_qiskit()
+    if n_iterations is None:
+        n_iterations = grover_optimal_iterations(n_qubits)
+    oracle = grover_oracle(n_qubits, marked_state)
+    diffusion = grover_diffusion(n_qubits)
+
+    qc = QuantumCircuit(n_qubits, name=f"grover_{marked_state}")
+    for q in range(n_qubits):
+        qc.h(q)
+    for _ in range(n_iterations):
+        qc.compose(oracle, inplace=True)
+        qc.compose(diffusion, inplace=True)
+    return qc
+
+
+def grover_success_probability(n_qubits: int, marked_state: int, n_iterations: int = None) -> float:
+    """Exact probability (statevector, no sampling) that measuring the
+    Grover circuit's output yields ``marked_state``."""
+    _require_qiskit()
+    qc = grover_circuit(n_qubits, marked_state, n_iterations)
+    sv = Statevector.from_instruction(qc)
+    probs = sv.probabilities()
+    return float(probs[marked_state])
+
+
+if __name__ == "__main__":
+    print("Teleportation fidelity for a few (theta, phi) message states:")
+    for theta, phi in [(0.3, 0.0), (1.0, 0.7), (2.5, 1.9)]:
+        fid = teleportation_output_fidelity((theta, phi))
+        print(f"  theta={theta:.2f} phi={phi:.2f}  fidelity={fid:.12f}")
+    print()
+
+    print("Superdense coding, all four two-bit messages:")
+    for bit_z in (0, 1):
+        for bit_x in (0, 1):
+            qc = superdense_coding_circuit(bit_z, bit_x)
+            decoded_z, decoded_x = decode_superdense_coding(qc)
+            print(
+                f"  sent (bit_z={bit_z}, bit_x={bit_x})  "
+                f"-> decoded (bit_z={decoded_z}, bit_x={decoded_x})  "
+                f"{'OK' if (decoded_z, decoded_x) == (bit_z, bit_x) else 'MISMATCH'}"
+            )
+    print()
+
+    print("Grover's algorithm, boosted probability of the marked state:")
+    for n_qubits in [3, 4, 5]:
+        marked = (2 ** n_qubits) // 3
+        n_iter = grover_optimal_iterations(n_qubits)
+        prob = grover_success_probability(n_qubits, marked, n_iter)
+        uniform = 1.0 / (2 ** n_qubits)
+        print(
+            f"  n_qubits={n_qubits}  marked={marked}  iterations={n_iter}  "
+            f"P(marked)={prob:.6f}  (uniform baseline={uniform:.6f})"
+        )

qang/ansatze.py

@@ -0,0 +1,171 @@
+"""
+qang.ansatze -- a small reusable library of variational ansatz
+constructors, including a genuinely qg-native ansatz whose free
+parameters are qg_Z values directly rather than raw angles.
+
+Two families:
+
+  1. Standard building blocks, generalized out of the one-off ansatz
+     written for examples/vqe_h2_qg_vs_theta.py so future VQE work in
+     qang doesn't have to redefine them:
+
+       - ``single_excitation_ansatz``   the minimal 1-parameter ansatz
+         used for the H2 example (X on the occupied qubit, RY(theta) on
+         the virtual qubit, then a CX back to the occupied qubit),
+         generalized to an arbitrary qubit pair on an arbitrary register
+         size. ``single_excitation_ansatz(2, 0, 1, theta)`` reproduces
+         examples/vqe_h2_qg_vs_theta.py's ``h2_ansatz(theta)`` exactly.
+
+       - ``hardware_efficient_ansatz``  the standard "HEA" pattern used
+         across the VQE literature: layers of single-qubit RY rotations
+         alternating with a ladder of CX entanglers.
+
+  2. The qg-native versions of both: ``qg_ry_layer``, and
+     ``hardware_efficient_ansatz_qg``, whose rotation parameters are
+     supplied directly as qg_Z values (qang.core.Qang) rather than raw
+     theta angles. This extends Future Research Direction #1's "construct
+     circuit parameters natively in qg" (already implemented at the
+     single-qubit-gate level in qang.qiskit_gate) up to the ansatz level:
+     a full variational layer can now be parameterized entirely in
+     physically meaningful qg units.
+
+This module is optional: importing ``qang`` itself never requires Qiskit.
+Only importing *this* module does, and it raises a clear, actionable error
+if Qiskit is not installed (same pattern as qang.qiskit_gate).
+"""
+
+from __future__ import annotations
+
+from typing import Sequence, Union
+
+from .core import Qang
+
+try:
+    from qiskit import QuantumCircuit
+
+    _QISKIT_AVAILABLE = True
+except ImportError:  # pragma: no cover - exercised only when qiskit is absent
+    _QISKIT_AVAILABLE = False
+
+
+def _require_qiskit():
+    if not _QISKIT_AVAILABLE:
+        raise ImportError(
+            "qang.ansatze requires Qiskit. Install it with "
+            "`pip install qiskit` (and, to run circuits, `pip install qiskit-aer`)."
+        )
+
+
+# --------------------------------------------------------------------- #
+# theta-space ansatze
+# --------------------------------------------------------------------- #
+def single_excitation_ansatz(
+    n_qubits: int, occupied_qubit: int, virtual_qubit: int, theta: float
+) -> "QuantumCircuit":
+    """
+    Minimal single-parameter excitation ansatz: X on ``occupied_qubit``
+    (the Hartree-Fock reference), RY(theta) on ``virtual_qubit``, then a
+    CX from ``virtual_qubit`` back to ``occupied_qubit`` to inject the
+    excitation. ``single_excitation_ansatz(2, 0, 1, theta)`` reproduces
+    examples/vqe_h2_qg_vs_theta.py's ``h2_ansatz`` exactly.
+    """
+    _require_qiskit()
+    if occupied_qubit == virtual_qubit:
+        raise ValueError("occupied_qubit and virtual_qubit must differ.")
+    if not (0 <= occupied_qubit < n_qubits and 0 <= virtual_qubit < n_qubits):
+        raise ValueError(f"qubit indices must lie in [0, {n_qubits - 1}].")
+
+    qc = QuantumCircuit(n_qubits, name="single_excitation")
+    qc.x(occupied_qubit)
+    qc.ry(theta, virtual_qubit)
+    qc.cx(virtual_qubit, occupied_qubit)
+    return qc
+
+
+def hardware_efficient_ansatz(
+    n_qubits: int, reps: int, params: Sequence[float]
+) -> "QuantumCircuit":
+    """
+    Standard hardware-efficient ansatz: ``reps + 1`` layers of RY
+    rotations (one angle per qubit per layer), each pair of consecutive
+    layers separated by a ladder of CX entanglers (qubit i -> i+1).
+
+    ``params`` must have exactly ``n_qubits * (reps + 1)`` entries, laid
+    out layer-by-layer (params[0:n_qubits] is the first rotation layer,
+    and so on).
+    """
+    _require_qiskit()
+    if reps < 0:
+        raise ValueError(f"reps must be >= 0, got {reps}.")
+    expected = n_qubits * (reps + 1)
+    params = list(params)
+    if len(params) != expected:
+        raise ValueError(f"expected {expected} params (n_qubits * (reps + 1)), got {len(params)}.")
+
+    qc = QuantumCircuit(n_qubits, name="hea")
+    idx = 0
+    for layer in range(reps + 1):
+        for q in range(n_qubits):
+            qc.ry(params[idx], q)
+            idx += 1
+        if layer < reps:
+            for q in range(n_qubits - 1):
+                qc.cx(q, q + 1)
+    return qc
+
+
+# --------------------------------------------------------------------- #
+# qg-native ansatze: parameters are qg_Z values, not raw angles
+# --------------------------------------------------------------------- #
+def qg_ry_layer(
+    qc: "QuantumCircuit", qubits: Sequence[int], qg_values: Sequence[Union[float, Qang]]
+) -> "QuantumCircuit":
+    """
+    Append one RY rotation per qubit in ``qubits``, with each angle
+    derived from a qg_Z value via ``Qang(qg_value).to_theta()`` rather
+    than supplied directly as a raw angle -- the ansatz-layer analogue of
+    qang.qiskit_gate.RQangGate, applied across a whole register at once.
+    """
+    _require_qiskit()
+    if len(qubits) != len(qg_values):
+        raise ValueError(
+            f"qubits and qg_values must have the same length, got {len(qubits)} and {len(qg_values)}."
+        )
+    for q, v in zip(qubits, qg_values):
+        qg = v if isinstance(v, Qang) else Qang(v, mode="polar")
+        qc.ry(qg.to_theta(), q)
+    return qc
+
+
+def hardware_efficient_ansatz_qg(
+    n_qubits: int, reps: int, qg_params: Sequence[Union[float, Qang]]
+) -> "QuantumCircuit":
+    """
+    Exactly ``hardware_efficient_ansatz``, except every rotation angle is
+    supplied as a qg_Z value (qang.core.Qang or a bare float in
+    [-1, 1]) instead of a raw theta -- so the whole variational ansatz can
+    be tuned directly in the physically meaningful qg unit end to end,
+    extending Future Research Direction #1 from a single gate to a full
+    multi-layer ansatz.
+    """
+    _require_qiskit()
+    if reps < 0:
+        raise ValueError(f"reps must be >= 0, got {reps}.")
+    expected = n_qubits * (reps + 1)
+    qg_params = list(qg_params)
+    if len(qg_params) != expected:
+        raise ValueError(
+            f"expected {expected} qg_params (n_qubits * (reps + 1)), got {len(qg_params)}."
+        )
+
+    qc = QuantumCircuit(n_qubits, name="hea_qg")
+    idx = 0
+    for layer in range(reps + 1):
+        layer_qubits = list(range(n_qubits))
+        layer_qg = qg_params[idx: idx + n_qubits]
+        qg_ry_layer(qc, layer_qubits, layer_qg)
+        idx += n_qubits
+        if layer < reps:
+            for q in range(n_qubits - 1):
+                qc.cx(q, q + 1)
+    return qc