Upload 6 files

quread/circuit_diagram.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+from typing import List, Dict, Any, Tuple
+import matplotlib.pyplot as plt
+import matplotlib.patches as patches
+
+Op = Dict[str, Any]
+
+def draw_circuit(ops: List[Op], n_qubits: int, title: str = "Circuit") -> plt.Figure:
+    # Basic, clean matplotlib circuit diagram: wires + boxes + CNOT dots
+    fig_w = max(7, 0.9*max(6, len(ops)+2))
+    fig_h = max(2.5, 0.6*n_qubits + 1)
+    fig, ax = plt.subplots(figsize=(fig_w, fig_h))
+
+    # coordinate system
+    x0 = 1.0
+    dx = 1.2
+    y_top = n_qubits - 1
+
+    # wires
+    for q in range(n_qubits):
+        y = y_top - q
+        ax.plot([0.5, x0 + dx*(len(ops)+1)], [y, y])
+        ax.text(0.1, y, f"q{q}", va="center")
+
+    # gates
+    for i, op in enumerate(ops):
+        x = x0 + dx*i
+        t = op.get("type")
+        if t == "single":
+            q = op["target"]
+            y = y_top - q
+            label = op["gate"]
+            if label in ("RX","RY","RZ"):
+                label = f"{label}({op['theta']:.2f})"
+            _box(ax, x, y, label)
+        elif t == "cnot":
+            c = op["control"]; tgt = op["target"]
+            yc = y_top - c; yt = y_top - tgt
+            # vertical line
+            ax.plot([x, x], [yc, yt])
+            # control dot
+            ax.add_patch(patches.Circle((x, yc), radius=0.12, fill=True))
+            # target plus in circle
+            ax.add_patch(patches.Circle((x, yt), radius=0.18, fill=False))
+            ax.plot([x-0.18, x+0.18], [yt, yt])
+            ax.plot([x, x], [yt-0.18, yt+0.18])
+        elif t == "measure":
+            # draw measurement on all wires (simple)
+            for q in range(n_qubits):
+                y = y_top - q
+                _box(ax, x, y, "M")
+            # stop drawing after measure
+            break
+
+    ax.set_title(title)
+    ax.set_xlim(0, x0 + dx*(len(ops)+2))
+    ax.set_ylim(-1, n_qubits)
+    ax.axis("off")
+    fig.tight_layout()
+    return fig
+
+def _box(ax, x: float, y: float, text: str) -> None:
+    w, h = 0.8, 0.55
+    rect = patches.FancyBboxPatch(
+        (x - w/2, y - h/2), w, h,
+        boxstyle="round,pad=0.08,rounding_size=0.08",
+        linewidth=1.2, facecolor="white"
+    )
+    ax.add_patch(rect)
+    ax.text(x, y, text, ha="center", va="center", fontsize=10)

quread/engine.py

@@ -0,0 +1,154 @@
+from __future__ import annotations
+import numpy as np
+from dataclasses import dataclass, field
+from typing import List, Dict, Any, Optional, Tuple
+
+from .gates import I, SINGLE_QUBIT_GATES, rx, ry, rz
+
+Op = Dict[str, Any]
+
+def _normalize_state(state: np.ndarray) -> np.ndarray:
+    norm = np.linalg.norm(state)
+    if norm == 0:
+        raise ValueError("State norm is zero; cannot normalize.")
+    return state / norm
+
+def _bit(value: int, bit_index_from_right: int) -> int:
+    # bit_index_from_right: 0 means least significant bit
+    return (value >> bit_index_from_right) & 1
+
+def _flip_bit(value: int, bit_index_from_right: int) -> int:
+    return value ^ (1 << bit_index_from_right)
+
+@dataclass
+class QuantumStateVector:
+    n_qubits: int
+    state: np.ndarray = field(init=False)
+    history: List[Op] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        if self.n_qubits < 1:
+            raise ValueError("n_qubits must be >= 1.")
+        dim = 2 ** self.n_qubits
+        self.state = np.zeros(dim, dtype=complex)
+        self.state[0] = 1.0 + 0j  # |0...0>
+
+    def reset(self) -> None:
+        dim = 2 ** self.n_qubits
+        self.state = np.zeros(dim, dtype=complex)
+        self.state[0] = 1.0 + 0j
+        self.history.clear()
+
+    # --------- Gate application (matrix-free, beginner friendly) ---------
+    def apply_single(self, gate_name: str, target: int, theta: Optional[float] = None) -> None:
+        if not (0 <= target < self.n_qubits):
+            raise ValueError("target out of range")
+        gate = None
+        if gate_name in SINGLE_QUBIT_GATES:
+            gate = SINGLE_QUBIT_GATES[gate_name]
+        elif gate_name == "RX":
+            if theta is None: raise ValueError("RX requires theta")
+            gate = rx(float(theta))
+        elif gate_name == "RY":
+            if theta is None: raise ValueError("RY requires theta")
+            gate = ry(float(theta))
+        elif gate_name == "RZ":
+            if theta is None: raise ValueError("RZ requires theta")
+            gate = rz(float(theta))
+        else:
+            raise ValueError(f"Unknown gate: {gate_name}")
+
+        # Apply using pairwise amplitude updates (no full 2^n x 2^n matrix)
+        # Convention: qubit 0 is the TOP wire in UI, but in basis indexing we treat
+        # qubit 0 as the most-significant bit (MSB). This keeps bitstrings readable.
+        msb_index = self.n_qubits - 1 - target  # convert "wire index" -> bit position from right
+
+        new_state = self.state.copy()
+        dim = len(self.state)
+        for basis in range(dim):
+            if _bit(basis, msb_index) == 0:
+                partner = _flip_bit(basis, msb_index)
+                a0 = self.state[basis]
+                a1 = self.state[partner]
+                # [a0'; a1'] = gate * [a0; a1]
+                new_state[basis]   = gate[0,0]*a0 + gate[0,1]*a1
+                new_state[partner] = gate[1,0]*a0 + gate[1,1]*a1
+        self.state = _normalize_state(new_state)
+
+        op: Op = {"type": "single", "gate": gate_name, "target": target}
+        if theta is not None:
+            op["theta"] = float(theta)
+        self.history.append(op)
+
+    def apply_cnot(self, control: int, target: int) -> None:
+        if control == target:
+            raise ValueError("control and target must be different")
+        if not (0 <= control < self.n_qubits) or not (0 <= target < self.n_qubits):
+            raise ValueError("control/target out of range")
+
+        c_bit = self.n_qubits - 1 - control
+        t_bit = self.n_qubits - 1 - target
+
+        new_state = self.state.copy()
+        dim = len(self.state)
+        visited = set()
+
+        for basis in range(dim):
+            if basis in visited:
+                continue
+            if _bit(basis, c_bit) == 1:
+                flipped = _flip_bit(basis, t_bit)
+                # swap amplitudes basis <-> flipped
+                visited.add(basis); visited.add(flipped)
+                new_state[basis], new_state[flipped] = self.state[flipped], self.state[basis]
+
+        self.state = _normalize_state(new_state)
+        self.history.append({"type": "cnot", "control": control, "target": target})
+
+    # --------- Measurement ---------
+    def probabilities(self) -> np.ndarray:
+        probs = np.abs(self.state) ** 2
+        total = float(np.sum(probs))
+        if total == 0:
+            return probs
+        return probs / total
+
+    def sample(self, shots: int = 1024) -> Dict[str, int]:
+        probs = self.probabilities()
+        dim = len(probs)
+        outcomes = np.random.choice(np.arange(dim), size=int(shots), p=probs)
+        counts: Dict[str, int] = {}
+        for idx in outcomes:
+            b = format(int(idx), f"0{self.n_qubits}b")
+            counts[b] = counts.get(b, 0) + 1
+        return dict(sorted(counts.items()))
+
+    def measure_collapse(self) -> str:
+        probs = self.probabilities()
+        dim = len(probs)
+        idx = int(np.random.choice(np.arange(dim), p=probs))
+        collapsed = np.zeros(dim, dtype=complex)
+        collapsed[idx] = 1.0 + 0j
+        self.state = collapsed
+        bitstring = format(idx, f"0{self.n_qubits}b")
+        self.history.append({"type": "measure", "result": bitstring})
+        return bitstring
+
+    # --------- Convenience helpers ---------
+    def ket_notation(self, max_terms: int = 16, tol: float = 1e-9) -> str:
+        # human readable statevector
+        terms = []
+        for i, amp in enumerate(self.state):
+            if abs(amp) > tol:
+                b = format(i, f"0{self.n_qubits}b")
+                terms.append((amp, b))
+        # sort by magnitude desc
+        terms.sort(key=lambda x: abs(x[0]), reverse=True)
+        terms = terms[:max_terms]
+        if not terms:
+            return "0"
+        parts = []
+        for amp, b in terms:
+            a = complex(amp)
+            parts.append(f"({a.real:+.4f}{a.imag:+.4f}j)|{b}⟩")
+        return " + ".join(parts).lstrip("+").strip()

quread/exporters.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+from typing import List, Dict, Any
+
+Op = Dict[str, Any]
+
+def to_openqasm2(ops: List[Op], n_qubits: int) -> str:
+    lines = ["OPENQASM 2.0;", 'include "qelib1.inc";', f"qreg q[{n_qubits}];", f"creg c[{n_qubits}];", ""]
+    for op in ops:
+        t = op.get("type")
+        if t == "single":
+            g = op["gate"].lower()
+            q = op["target"]
+            if op["gate"] in ("RX","RY","RZ"):
+                theta = op["theta"]
+                g = op["gate"].lower()
+                lines.append(f"{g}({theta}) q[{q}];")
+            else:
+                lines.append(f"{g} q[{q}];")
+        elif t == "cnot":
+            lines.append(f"cx q[{op['control']}],q[{op['target']}];")
+        elif t == "measure":
+            # measure all qubits
+            lines.append("measure q -> c;")
+            break
+    return "\n".join(lines).strip() + "\n"
+
+def to_qiskit(ops: List[Op], n_qubits: int) -> str:
+    lines = [
+        "from qiskit import QuantumCircuit",
+        "",
+        f"qc = QuantumCircuit({n_qubits}, {n_qubits})",
+        ""
+    ]
+    for op in ops:
+        t = op.get("type")
+        if t == "single":
+            g = op["gate"]
+            q = op["target"]
+            if g in ("RX","RY","RZ"):
+                lines.append(f"qc.{g.lower()}({op['theta']}, {q})")
+            else:
+                lines.append(f"qc.{g.lower()}({q})")
+        elif t == "cnot":
+            lines.append(f"qc.cx({op['control']}, {op['target']})")
+        elif t == "measure":
+            lines.append("qc.measure(range(qc.num_qubits), range(qc.num_clbits))")
+            break
+    lines.append("")
+    lines.append("print(qc)")
+    return "\n".join(lines).strip() + "\n"
+
+def to_cirq(ops: List[Op], n_qubits: int) -> str:
+    lines = [
+        "import cirq",
+        "",
+        f"q = cirq.LineQubit.range({n_qubits})",
+        "circuit = cirq.Circuit()",
+        ""
+    ]
+    for op in ops:
+        t = op.get("type")
+        if t == "single":
+            g = op["gate"]
+            qu = op["target"]
+            if g in ("RX","RY","RZ"):
+                theta = op["theta"]
+                # Cirq uses radians in exponent form
+                if g == "RX":
+                    lines.append(f"circuit.append(cirq.rx({theta}).on(q[{qu}]))")
+                elif g == "RY":
+                    lines.append(f"circuit.append(cirq.ry({theta}).on(q[{qu}]))")
+                else:
+                    lines.append(f"circuit.append(cirq.rz({theta}).on(q[{qu}]))")
+            else:
+                map_ = {"H":"H","X":"X","Y":"Y","Z":"Z","S":"S","T":"T","I":"I"}
+                lines.append(f"circuit.append(cirq.{map_[g]}.on(q[{qu}]))")
+        elif t == "cnot":
+            lines.append(f"circuit.append(cirq.CNOT(q[{op['control']}], q[{op['target']}]))")
+        elif t == "measure":
+            lines.append("circuit.append(cirq.measure(*q, key='m'))")
+            break
+    lines.append("")
+    lines.append("print(circuit)")
+    return "\n".join(lines).strip() + "\n"

quread/gates.py

@@ -0,0 +1,26 @@
+import numpy as np
+
+# Single-qubit gates (2x2)
+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)
+H = (1/np.sqrt(2)) * np.array([[1, 1], [1, -1]], dtype=complex)
+S = np.array([[1, 0], [0, 1j]], dtype=complex)
+T = np.array([[1, 0], [0, np.exp(1j*np.pi/4)]], dtype=complex)
+
+def rz(theta: float) -> np.ndarray:
+    return np.array([[np.exp(-1j*theta/2), 0],
+                     [0, np.exp(1j*theta/2)]], dtype=complex)
+
+def ry(theta: float) -> np.ndarray:
+    return np.array([[np.cos(theta/2), -np.sin(theta/2)],
+                     [np.sin(theta/2),  np.cos(theta/2)]], dtype=complex)
+
+def rx(theta: float) -> np.ndarray:
+    return np.array([[np.cos(theta/2), -1j*np.sin(theta/2)],
+                     [-1j*np.sin(theta/2), np.cos(theta/2)]], dtype=complex)
+
+SINGLE_QUBIT_GATES = {
+    "I": I, "X": X, "Y": Y, "Z": Z, "H": H, "S": S, "T": T
+}

quread/llm_explain.py

@@ -0,0 +1,135 @@
+# quread/llm_explain.py
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional, Tuple
+
+from huggingface_hub import InferenceClient
+
+
+@dataclass
+class ExplainConfig:
+    model_id: str = "HuggingFaceH4/zephyr-7b-beta"  # you can change later
+    provider: str = "hf-inference"
+    max_new_tokens: int = 280
+    temperature: float = 0.2
+
+
+def _build_grounded_prompt(
+    n_qubits: int,
+    history: List[Dict[str, Any]],
+    state_ket: str,
+    probs_top: List[Tuple[str, float]],
+    shots: Optional[int] = None,
+) -> str:
+    """
+    Prompt is explicitly grounded: it includes only circuit + computed outputs.
+    The model is instructed not to invent values.
+    """
+    ops_lines = []
+    for op in history:
+        if op.get("type") == "single":
+            ops_lines.append(f"- {op['gate']}(q{op['target']})")
+        elif op.get("type") == "cnot":
+            ops_lines.append(f"- CNOT(q{op['control']} -> q{op['target']})")
+        else:
+            ops_lines.append(f"- {op}")
+
+    top_lines = [f"- {b}: {p:.4f}" for b, p in probs_top]
+
+    shots_line = f"Shots: {shots}\n" if shots is not None else ""
+
+    return f"""
+You are a quantum computing tutor and debugger.
+Only use the data provided below. Do not invent values not present here.
+
+Task:
+1) Explain what the circuit did, gate-by-gate, in plain English.
+2) Explain whether the result suggests superposition and/or entanglement.
+3) Explain why the top measurement outcomes make sense from interference.
+4) Provide 2 debugging tips (e.g., qubit ordering, control/target confusion).
+
+Data:
+Qubits: {n_qubits}
+Circuit operations:
+{chr(10).join(ops_lines)}
+
+Final state (ket-like summary):
+{state_ket}
+
+Top measurement probabilities:
+{chr(10).join(top_lines)}
+
+{shots_line}
+Return a concise explanation with bullet points and short paragraphs.
+""".strip()
+
+
+def _get_token() -> Optional[str]:
+    return os.getenv("HF_TOKEN")
+
+
+def explain_circuit_with_hf(
+    n_qubits: int,
+    history: List[Dict[str, Any]],
+    state_ket: str,
+    probs_top: List[Tuple[str, float]],
+    *,
+    shots: Optional[int] = None,
+    cfg: Optional[ExplainConfig] = None,
+) -> str:
+    """
+    Calls Hugging Face Inference Providers via huggingface_hub.InferenceClient.
+
+    Tries chat-completion first (if supported by model), then text-generation.
+    """
+    cfg = cfg or ExplainConfig()
+    token = _get_token()
+    if not token:
+        return "HF_TOKEN is not set. Please set it as an environment variable."
+
+    client = InferenceClient(provider=cfg.provider, token=token)
+
+    prompt = _build_grounded_prompt(
+        n_qubits=n_qubits,
+        history=history,
+        state_ket=state_ket,
+        probs_top=probs_top,
+        shots=shots,
+    )
+
+    # 1) Try Chat Completion
+    try:
+        resp = client.chat_completion(
+            model=cfg.model_id,
+            messages=[
+                {"role": "system", "content": "You are a helpful quantum tutor."},
+                {"role": "user", "content": prompt},
+            ],
+            max_tokens=cfg.max_new_tokens,
+            temperature=cfg.temperature,
+        )
+        # huggingface_hub returns a structured object
+        return resp.choices[0].message.content.strip()
+    except Exception:
+        pass
+
+    # 2) Fallback: Text Generation
+    try:
+        out = client.text_generation(
+            model=cfg.model_id,
+            prompt=prompt,
+            max_new_tokens=cfg.max_new_tokens,
+            temperature=cfg.temperature,
+        )
+        return out.strip()
+    except Exception as e:
+        return (
+            "LLM call failed.\n\n"
+            f"Model: {cfg.model_id}\n"
+            f"Provider: {cfg.provider}\n"
+            f"Error: {repr(e)}\n\n"
+            "Try changing the model_id to a different HF model that supports "
+            "text-generation or chat-completion via Inference Providers."
+        )