qomputing-simulator 0.1.0__py3-none-any.whl

examples/library_usage.py

@@ -0,0 +1,30 @@
+#!/usr/bin/env python3
+"""Example: using the state-vector simulator as a library."""
+
+from qomputing_simulator import (
+    QuantumCircuit,
+    load_circuit,
+    random_circuit,
+    run,
+    run_xeb,
+)
+
+# 1) Build a circuit in code and run it (no shots = state vector only)
+circuit = QuantumCircuit(2)
+circuit.h(0).cx(0, 1)
+result = run(circuit)
+print("Bell circuit final state (real):", result.final_state.real.round(4).tolist())
+print("Probabilities:", result.probabilities.round(4).tolist())
+
+# 2) Run with measurement shots
+result = run(circuit, shots=1000, seed=42)
+print("Counts:", result.counts)
+
+# 3) Load a circuit from JSON and run
+# result = run("circuits/example.json", shots=512, seed=123)
+
+# 4) Random circuit and XEB
+qc = random_circuit(num_qubits=3, depth=5, seed=7)
+xeb = run_xeb(qc, shots=1000, seed=7)
+print("XEB fidelity:", round(xeb.fidelity, 4))
+print("Sample probabilities:", xeb.sample_probabilities)

qomputing_simulator/__init__.py

@@ -0,0 +1,22 @@
+"""State Vector Simulator package."""
+
+from .circuit import Gate, QuantumCircuit
+from .engine import SimulationResult, StateVectorSimulator
+from .run import load_circuit, random_circuit, run, run_xeb
+from .xeb import LinearXEBResult, compute_linear_xeb_fidelity, run_linear_xeb_experiment
+
+__all__ = [
+    "Gate",
+    "QuantumCircuit",
+    "StateVectorSimulator",
+    "SimulationResult",
+    "LinearXEBResult",
+    "compute_linear_xeb_fidelity",
+    "run_linear_xeb_experiment",
+    # Library API
+    "load_circuit",
+    "run",
+    "run_xeb",
+    "random_circuit",
+]
+

qomputing_simulator/circuit.py

@@ -0,0 +1,231 @@
+"""Circuit primitives for the state vector simulator."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, Iterable, List, Mapping, Sequence, Tuple
+
+
+def _ensure_tuple(values: Sequence[int]) -> Tuple[int, ...]:
+    return tuple(int(v) for v in values)
+
+
+@dataclass(frozen=True)
+class Gate:
+    """Immutable gate description."""
+
+    name: str
+    targets: Tuple[int, ...]
+    controls: Tuple[int, ...] = field(default_factory=tuple)
+    params: Mapping[str, float] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        name = self.name.lower()
+        object.__setattr__(self, "name", name)
+
+        if not self.targets:
+            raise ValueError("Gate must have at least one target qubit")
+        if len(set(self.targets)) != len(self.targets):
+            raise ValueError(f"Duplicate target qubits in gate {self.name}")
+        if any(t < 0 for t in self.targets):
+            raise ValueError("Target qubit indices must be non-negative")
+
+        if len(set(self.controls)) != len(self.controls):
+            raise ValueError(f"Duplicate control qubits in gate {self.name}")
+        if any(c < 0 for c in self.controls):
+            raise ValueError("Control qubit indices must be non-negative")
+
+        overlap = set(self.targets) & set(self.controls)
+        if overlap:
+            raise ValueError(f"Control and target sets overlap for gate {self.name}: {overlap}")
+
+
+class QuantumCircuit:
+    """Simple representation of a quantum circuit."""
+
+    def __init__(self, num_qubits: int) -> None:
+        if num_qubits <= 0:
+            raise ValueError("Circuit must have at least one qubit")
+        self.num_qubits = int(num_qubits)
+        self._gates: List[Gate] = []
+
+    @property
+    def gates(self) -> Tuple[Gate, ...]:
+        return tuple(self._gates)
+
+    def add_gate(
+        self,
+        name: str,
+        targets: Sequence[int],
+        *,
+        controls: Sequence[int] | None = None,
+        params: Mapping[str, float] | None = None,
+    ) -> "QuantumCircuit":
+        gate = Gate(
+            name=name,
+            targets=_ensure_tuple(targets),
+            controls=_ensure_tuple(controls or ()),
+            params=dict(params or {}),
+        )
+        self._validate_gate_qubits(gate)
+        self._gates.append(gate)
+        return self
+
+    # Convenience builders -------------------------------------------------
+    def i(self, target: int) -> "QuantumCircuit":
+        return self.add_gate("id", [target])
+
+    def x(self, target: int) -> "QuantumCircuit":
+        return self.add_gate("x", [target])
+
+    def y(self, target: int) -> "QuantumCircuit":
+        return self.add_gate("y", [target])
+
+    def z(self, target: int) -> "QuantumCircuit":
+        return self.add_gate("z", [target])
+
+    def h(self, target: int) -> "QuantumCircuit":
+        return self.add_gate("h", [target])
+
+    def s(self, target: int) -> "QuantumCircuit":
+        return self.add_gate("s", [target])
+
+    def sdg(self, target: int) -> "QuantumCircuit":
+        return self.add_gate("sdg", [target])
+
+    def t(self, target: int) -> "QuantumCircuit":
+        return self.add_gate("t", [target])
+
+    def tdg(self, target: int) -> "QuantumCircuit":
+        return self.add_gate("tdg", [target])
+
+    def sx(self, target: int) -> "QuantumCircuit":
+        return self.add_gate("sx", [target])
+
+    def sxdg(self, target: int) -> "QuantumCircuit":
+        return self.add_gate("sxdg", [target])
+
+    def rx(self, target: int, theta: float) -> "QuantumCircuit":
+        return self.add_gate("rx", [target], params={"theta": float(theta)})
+
+    def ry(self, target: int, theta: float) -> "QuantumCircuit":
+        return self.add_gate("ry", [target], params={"theta": float(theta)})
+
+    def rz(self, target: int, theta: float) -> "QuantumCircuit":
+        return self.add_gate("rz", [target], params={"theta": float(theta)})
+
+    def u1(self, target: int, lam: float) -> "QuantumCircuit":
+        return self.add_gate("u1", [target], params={"lambda": float(lam)})
+
+    def u2(self, target: int, phi: float, lam: float) -> "QuantumCircuit":
+        return self.add_gate("u2", [target], params={"phi": float(phi), "lambda": float(lam)})
+
+    def u3(self, target: int, theta: float, phi: float, lam: float) -> "QuantumCircuit":
+        return self.add_gate(
+            "u3",
+            [target],
+            params={"theta": float(theta), "phi": float(phi), "lambda": float(lam)},
+        )
+
+    def cx(self, control: int, target: int) -> "QuantumCircuit":
+        return self.add_gate("cx", [target], controls=[control])
+
+    def cy(self, control: int, target: int) -> "QuantumCircuit":
+        return self.add_gate("cy", [target], controls=[control])
+
+    def cz(self, control: int, target: int) -> "QuantumCircuit":
+        return self.add_gate("cz", [target], controls=[control])
+
+    def cp(self, control: int, target: int, phi: float) -> "QuantumCircuit":
+        return self.add_gate("cp", [target], controls=[control], params={"phi": float(phi)})
+
+    def swap(self, q1: int, q2: int) -> "QuantumCircuit":
+        if q1 == q2:
+            raise ValueError("Swap operands must refer to distinct qubits")
+        return self.add_gate("swap", [q1, q2])
+
+    def iswap(self, q1: int, q2: int) -> "QuantumCircuit":
+        if q1 == q2:
+            raise ValueError("iswap operands must refer to distinct qubits")
+        return self.add_gate("iswap", [q1, q2])
+
+    def sqrt_iswap(self, q1: int, q2: int) -> "QuantumCircuit":
+        if q1 == q2:
+            raise ValueError("sqrtiswap operands must refer to distinct qubits")
+        return self.add_gate("sqrtiswap", [q1, q2])
+
+    def rxx(self, q1: int, q2: int, theta: float) -> "QuantumCircuit":
+        if q1 == q2:
+            raise ValueError("rxx operands must refer to distinct qubits")
+        return self.add_gate("rxx", [q1, q2], params={"theta": float(theta)})
+
+    def ryy(self, q1: int, q2: int, theta: float) -> "QuantumCircuit":
+        if q1 == q2:
+            raise ValueError("ryy operands must refer to distinct qubits")
+        return self.add_gate("ryy", [q1, q2], params={"theta": float(theta)})
+
+    def rzz(self, q1: int, q2: int, theta: float) -> "QuantumCircuit":
+        if q1 == q2:
+            raise ValueError("rzz operands must refer to distinct qubits")
+        return self.add_gate("rzz", [q1, q2], params={"theta": float(theta)})
+
+    def csx(self, control: int, target: int) -> "QuantumCircuit":
+        return self.add_gate("csx", [target], controls=[control])
+
+    def ccx(self, control1: int, control2: int, target: int) -> "QuantumCircuit":
+        return self.add_gate("ccx", [target], controls=[control1, control2])
+
+    def ccz(self, control1: int, control2: int, target: int) -> "QuantumCircuit":
+        return self.add_gate("ccz", [target], controls=[control1, control2])
+
+    def cswap(self, control: int, q1: int, q2: int) -> "QuantumCircuit":
+        if q1 == q2:
+            raise ValueError("cswap target qubits must be distinct")
+        return self.add_gate("cswap", [q1, q2], controls=[control])
+
+    # Serialisation --------------------------------------------------------
+    def to_dict(self) -> Dict[str, object]:
+        return {
+            "num_qubits": self.num_qubits,
+            "gates": [
+                {
+                    "name": gate.name,
+                    "targets": list(gate.targets),
+                    **(
+                        {"controls": list(gate.controls)}
+                        if gate.controls
+                        else {}
+                    ),
+                    **({"params": dict(gate.params)} if gate.params else {}),
+                }
+                for gate in self._gates
+            ],
+        }
+
+    @classmethod
+    def from_dict(cls, payload: Mapping[str, object]) -> "QuantumCircuit":
+        num_qubits = int(payload["num_qubits"])
+        circuit = cls(num_qubits)
+        for gate_payload in payload.get("gates", []):
+            if not isinstance(gate_payload, Mapping):
+                raise TypeError("Gate payload must be a mapping")
+            circuit.add_gate(
+                str(gate_payload["name"]),
+                gate_payload.get("targets", ()),
+                controls=gate_payload.get("controls"),
+                params=gate_payload.get("params"),
+            )
+        return circuit
+
+    # Internal helpers -----------------------------------------------------
+    def _validate_gate_qubits(self, gate: Gate) -> None:
+        for index in gate.targets + gate.controls:
+            if index < 0 or index >= self.num_qubits:
+                raise ValueError(
+                    f"Qubit index {index} for gate {gate.name} "
+                    f"is out of range for circuit with {self.num_qubits} qubits",
+                )
+
+    def __repr__(self) -> str:  # pragma: no cover - debug helper
+        return f"QuantumCircuit(num_qubits={self.num_qubits}, gates={self._gates!r})"
+

qomputing_simulator/circuit_builders.py

@@ -0,0 +1,185 @@
+"""Circuit builders for programmatic use and random-circuit XEB."""
+
+from __future__ import annotations
+
+import math
+import random
+from typing import Dict, Iterable, Sequence, Tuple
+
+from .circuit import QuantumCircuit
+from .gates import (
+    DEFAULT_MULTI_QUBIT_GATES,
+    DEFAULT_SINGLE_QUBIT_GATES,
+    DEFAULT_TWO_QUBIT_GATES,
+)
+
+
+def random_circuit(
+    *,
+    num_qubits: int,
+    depth: int,
+    single_qubit_gates: Iterable[str] | None = None,
+    two_qubit_gates: Iterable[str] | None = None,
+    multi_qubit_gates: Iterable[str] | None = None,
+    seed: int | None = None,
+) -> QuantumCircuit:
+    """Build a random circuit with one layer of single-qubit gates and optional two/multi-qubit gates per depth.
+
+    Args:
+        num_qubits: Number of qubits.
+        depth: Number of layers (each layer: single-qubit gates on all qubits, then one two-qubit, optionally one multi-qubit).
+        single_qubit_gates: Gate names to sample from; default is DEFAULT_SINGLE_QUBIT_GATES.
+        two_qubit_gates: Two-qubit gate names; default is DEFAULT_TWO_QUBIT_GATES.
+        multi_qubit_gates: Multi-qubit gate names (e.g. ccx, ccz, cswap); default is DEFAULT_MULTI_QUBIT_GATES.
+        seed: Random seed for reproducibility.
+
+    Returns:
+        A QuantumCircuit ready for simulation or XEB.
+    """
+    if num_qubits <= 0:
+        raise ValueError("Number of qubits must be positive")
+    if depth <= 0:
+        raise ValueError("Depth must be positive")
+
+    single_qubit_gates = list(single_qubit_gates or DEFAULT_SINGLE_QUBIT_GATES)
+    if not single_qubit_gates:
+        raise ValueError("Single-qubit gate set must not be empty")
+
+    two_qubit_gates = list(two_qubit_gates or DEFAULT_TWO_QUBIT_GATES)
+    multi_qubit_gates = list(multi_qubit_gates or DEFAULT_MULTI_QUBIT_GATES)
+    if num_qubits > 1 and not two_qubit_gates:
+        raise ValueError("Two-qubit gate set must not be empty when num_qubits > 1")
+
+    multi_specs: Dict[str, Tuple[int, int]] = {
+        "ccx": (2, 1),
+        "ccz": (2, 1),
+        "cswap": (1, 2),
+    }
+
+    rng = random.Random(seed)
+    circuit = QuantumCircuit(num_qubits)
+
+    for _ in range(depth):
+        for qubit in range(num_qubits):
+            gate_name = rng.choice(single_qubit_gates)
+            _apply_single_qubit_gate(circuit, gate_name, qubit, rng)
+
+        if num_qubits > 1 and two_qubit_gates:
+            gate_name = rng.choice(two_qubit_gates)
+            q1, q2 = rng.sample(range(num_qubits), 2)
+            _apply_two_qubit_gate(circuit, gate_name, q1, q2, rng)
+
+        if num_qubits > 2 and multi_qubit_gates:
+            gate_name = rng.choice(multi_qubit_gates)
+            if gate_name not in multi_specs:
+                raise ValueError(f"Unsupported multi-qubit gate in random circuit: {gate_name}")
+            controls_required, targets_required = multi_specs[gate_name]
+            total_required = controls_required + targets_required
+            if num_qubits >= total_required:
+                selected = rng.sample(range(num_qubits), total_required)
+                controls = selected[:controls_required]
+                targets = selected[controls_required:]
+                _apply_multi_qubit_gate(circuit, gate_name, controls, targets, rng)
+
+    return circuit
+
+
+def _apply_single_qubit_gate(
+    circuit: QuantumCircuit,
+    gate_name: str,
+    qubit: int,
+    rng: random.Random,
+) -> None:
+    two_pi = 2.0 * math.pi
+    if gate_name == "id":
+        circuit.i(qubit)
+    elif gate_name == "x":
+        circuit.x(qubit)
+    elif gate_name == "y":
+        circuit.y(qubit)
+    elif gate_name == "z":
+        circuit.z(qubit)
+    elif gate_name == "h":
+        circuit.h(qubit)
+    elif gate_name == "s":
+        circuit.s(qubit)
+    elif gate_name == "sdg":
+        circuit.sdg(qubit)
+    elif gate_name == "t":
+        circuit.t(qubit)
+    elif gate_name == "tdg":
+        circuit.tdg(qubit)
+    elif gate_name == "sx":
+        circuit.sx(qubit)
+    elif gate_name == "sxdg":
+        circuit.sxdg(qubit)
+    elif gate_name == "rx":
+        circuit.rx(qubit, rng.uniform(0.0, two_pi))
+    elif gate_name == "ry":
+        circuit.ry(qubit, rng.uniform(0.0, two_pi))
+    elif gate_name == "rz":
+        circuit.rz(qubit, rng.uniform(0.0, two_pi))
+    elif gate_name == "u1":
+        circuit.u1(qubit, rng.uniform(0.0, two_pi))
+    elif gate_name == "u2":
+        circuit.u2(qubit, rng.uniform(0.0, two_pi), rng.uniform(0.0, two_pi))
+    elif gate_name == "u3":
+        circuit.u3(
+            qubit,
+            rng.uniform(0.0, two_pi),
+            rng.uniform(0.0, two_pi),
+            rng.uniform(0.0, two_pi),
+        )
+    else:
+        raise ValueError(f"Unsupported single-qubit gate: {gate_name}")
+
+
+def _apply_two_qubit_gate(
+    circuit: QuantumCircuit,
+    gate_name: str,
+    q1: int,
+    q2: int,
+    rng: random.Random,
+) -> None:
+    two_pi = 2.0 * math.pi
+    if gate_name == "cx":
+        circuit.cx(q1, q2)
+    elif gate_name == "cy":
+        circuit.cy(q1, q2)
+    elif gate_name == "cz":
+        circuit.cz(q1, q2)
+    elif gate_name == "cp":
+        circuit.cp(q1, q2, rng.uniform(0.0, two_pi))
+    elif gate_name == "swap":
+        circuit.swap(q1, q2)
+    elif gate_name == "iswap":
+        circuit.iswap(q1, q2)
+    elif gate_name == "sqrtiswap":
+        circuit.sqrt_iswap(q1, q2)
+    elif gate_name == "rxx":
+        circuit.rxx(q1, q2, rng.uniform(0.0, two_pi))
+    elif gate_name == "ryy":
+        circuit.ryy(q1, q2, rng.uniform(0.0, two_pi))
+    elif gate_name == "rzz":
+        circuit.rzz(q1, q2, rng.uniform(0.0, two_pi))
+    elif gate_name == "csx":
+        circuit.csx(q1, q2)
+    else:
+        raise ValueError(f"Unsupported two-qubit gate in random circuit: {gate_name}")
+
+
+def _apply_multi_qubit_gate(
+    circuit: QuantumCircuit,
+    gate_name: str,
+    controls: Sequence[int],
+    targets: Sequence[int],
+    rng: random.Random,
+) -> None:
+    if gate_name == "ccx":
+        circuit.ccx(controls[0], controls[1], targets[0])
+    elif gate_name == "ccz":
+        circuit.ccz(controls[0], controls[1], targets[0])
+    elif gate_name == "cswap":
+        circuit.cswap(controls[0], targets[0], targets[1])
+    else:
+        raise ValueError(f"Unsupported multi-qubit gate in random circuit: {gate_name}")

qomputing_simulator/cli.py

@@ -0,0 +1,121 @@
+"""Command line interface for the state vector simulator."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+from typing import Sequence
+
+from .circuit import QuantumCircuit
+from .circuit_builders import random_circuit
+from .gates import (
+    DEFAULT_MULTI_QUBIT_GATES,
+    DEFAULT_SINGLE_QUBIT_GATES,
+    DEFAULT_TWO_QUBIT_GATES,
+)
+from .simulator import StateVectorSimulator
+from .xeb import run_linear_xeb_experiment
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "simulate":
+        return _cmd_simulate(args)
+    if args.command == "random-circuit":
+        return _cmd_random_circuit(args)
+
+    parser.print_help()
+    return 0
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="State vector simulator CLI")
+    subparsers = parser.add_subparsers(dest="command")
+
+    simulate_parser = subparsers.add_parser("simulate", help="Simulate a circuit from JSON")
+    simulate_parser.add_argument("--circuit", type=Path, required=True, help="Path to circuit JSON file")
+    simulate_parser.add_argument("--shots", type=int, default=0, help="Number of measurement shots to sample")
+    simulate_parser.add_argument("--seed", type=int, default=None, help="Random seed for sampling")
+
+    rand_parser = subparsers.add_parser("random-circuit", help="Generate a random circuit and run XEB")
+    rand_parser.add_argument("--qubits", type=int, required=True, help="Number of qubits")
+    rand_parser.add_argument("--depth", type=int, required=True, help="Circuit depth (layers)")
+    rand_parser.add_argument("--shots", type=int, required=True, help="Number of measurement shots")
+    rand_parser.add_argument("--seed", type=int, default=None, help="Random seed for circuit generation and sampling")
+    rand_parser.add_argument(
+        "--single-qubit-gates",
+        type=str,
+        nargs="*",
+        default=DEFAULT_SINGLE_QUBIT_GATES,
+        help="Set of single-qubit gates to sample from",
+    )
+    rand_parser.add_argument(
+        "--two-qubit-gates",
+        type=str,
+        nargs="*",
+        default=DEFAULT_TWO_QUBIT_GATES,
+        help="Set of two-qubit gates to sample from",
+    )
+    rand_parser.add_argument(
+        "--multi-qubit-gates",
+        type=str,
+        nargs="*",
+        default=DEFAULT_MULTI_QUBIT_GATES,
+        help="Set of multi-qubit gates (three or more qubits) to sample from",
+    )
+
+    return parser
+
+
+def _cmd_simulate(args: argparse.Namespace) -> int:
+    circuit = _load_circuit(args.circuit)
+    simulator = StateVectorSimulator()
+    result = simulator.run(circuit, shots=args.shots, seed=args.seed)
+    payload = {
+        "num_qubits": circuit.num_qubits,
+        "shots": result.shots,
+        "final_state_real": result.final_state.real.tolist(),
+        "final_state_imag": result.final_state.imag.tolist(),
+        "probabilities": result.probabilities.tolist(),
+        "counts": result.counts,
+        "samples": result.samples,
+    }
+    print(json.dumps(payload, indent=2))
+    return 0
+
+
+def _cmd_random_circuit(args: argparse.Namespace) -> int:
+    circuit = random_circuit(
+        num_qubits=args.qubits,
+        depth=args.depth,
+        single_qubit_gates=args.single_qubit_gates,
+        two_qubit_gates=args.two_qubit_gates,
+        multi_qubit_gates=args.multi_qubit_gates,
+        seed=args.seed,
+    )
+    xeb_result = run_linear_xeb_experiment(
+        circuit,
+        shots=args.shots,
+        seed=args.seed,
+    )
+    payload = {
+        "num_qubits": circuit.num_qubits,
+        "depth": args.depth,
+        "shots": args.shots,
+        "fidelity": xeb_result.fidelity,
+        "sample_probabilities": xeb_result.sample_probabilities,
+    }
+    print(json.dumps(payload, indent=2))
+    return 0
+
+
+def _load_circuit(path: Path) -> QuantumCircuit:
+    from .run import load_circuit
+    return load_circuit(path)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())
+

qomputing_simulator/engine/__init__.py

@@ -0,0 +1,7 @@
+"""Simulation engine entry points."""
+
+from .result import SimulationResult
+from .statevector import StateVectorSimulator
+
+__all__ = ["SimulationResult", "StateVectorSimulator"]
+

qomputing_simulator/engine/measurements.py

@@ -0,0 +1,26 @@
+"""Measurement sampling utilities."""
+
+from __future__ import annotations
+
+from typing import Dict, Iterable, List
+
+import numpy as np
+
+
+def sample_measurements(
+    probabilities: np.ndarray,
+    num_qubits: int,
+    shots: int,
+    rng: np.random.Generator,
+) -> List[str]:
+    probabilities = probabilities / probabilities.sum()
+    basis_indices = rng.choice(len(probabilities), size=shots, p=probabilities)
+    return [format(index, f"0{num_qubits}b") for index in basis_indices]
+
+
+def counts_from_samples(samples: Iterable[str]) -> Dict[str, int]:
+    counts: Dict[str, int] = {}
+    for measurement in samples:
+        counts[measurement] = counts.get(measurement, 0) + 1
+    return counts
+

qomputing_simulator/engine/registry.py

@@ -0,0 +1,32 @@
+"""Gate registry mapping names to handler implementations."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from ..circuit import Gate
+from ..gates import (
+    MULTI_QUBIT_HANDLERS,
+    SINGLE_QUBIT_HANDLERS,
+    TWO_QUBIT_HANDLERS,
+)
+
+
+def apply_gate(
+    state: np.ndarray,
+    gate: Gate,
+    num_qubits: int,
+    dtype: np.dtype,
+) -> np.ndarray:
+    name = gate.name
+    if name in SINGLE_QUBIT_HANDLERS and not gate.controls:
+        handler = SINGLE_QUBIT_HANDLERS[name]
+        return handler(state, gate, num_qubits, dtype)
+    if name in TWO_QUBIT_HANDLERS:
+        handler = TWO_QUBIT_HANDLERS[name]
+        return handler(state, gate, num_qubits, dtype)
+    if name in MULTI_QUBIT_HANDLERS:
+        handler = MULTI_QUBIT_HANDLERS[name]
+        return handler(state, gate, num_qubits, dtype)
+    raise ValueError(f"Unsupported gate: {gate.name}")
+

qomputing_simulator/engine/result.py

@@ -0,0 +1,31 @@
+"""Simulation result dataclass."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict, List, Optional
+
+import numpy as np
+
+from ..circuit import QuantumCircuit
+
+
+@dataclass
+class SimulationResult:
+    """Results of a simulation run."""
+
+    circuit: QuantumCircuit
+    final_state: np.ndarray
+    probabilities: np.ndarray
+    shots: Optional[int] = None
+    samples: Optional[List[str]] = None
+    counts: Optional[Dict[str, int]] = None
+
+    def bitstring_probabilities(self) -> Dict[str, float]:
+        """Return probabilities keyed by little-endian bitstrings."""
+        probs: Dict[str, float] = {}
+        for index, probability in enumerate(self.probabilities):
+            bitstring = format(index, f"0{self.circuit.num_qubits}b")
+            probs[bitstring] = float(probability)
+        return probs
+