qomputing-simulator 0.1.0__py3-none-any.whl

qomputing_simulator/engine/statevector.py

@@ -0,0 +1,49 @@
+"""NumPy-based state vector simulator."""
+
+from __future__ import annotations
+
+from typing import Dict, List, Optional
+
+import numpy as np
+
+from .. import linalg
+from ..circuit import QuantumCircuit
+from . import measurements, registry
+from .result import SimulationResult
+
+
+class StateVectorSimulator:
+    """State vector simulator delegating gate logic to handler modules."""
+
+    def __init__(self, *, dtype: np.dtype = np.complex128) -> None:
+        self.dtype = dtype
+
+    def run(
+        self,
+        circuit: QuantumCircuit,
+        *,
+        shots: int | None = None,
+        seed: int | None = None,
+    ) -> SimulationResult:
+        state = linalg.initial_state(circuit.num_qubits, dtype=self.dtype)
+        for gate in circuit.gates:
+            state = registry.apply_gate(state, gate, circuit.num_qubits, self.dtype)
+
+        probabilities = np.abs(state) ** 2
+        result_shots = shots if shots and shots > 0 else None
+        samples: Optional[List[str]] = None
+        counts: Optional[Dict[str, int]] = None
+        if result_shots:
+            rng = np.random.default_rng(seed)
+            samples = measurements.sample_measurements(probabilities, circuit.num_qubits, result_shots, rng)
+            counts = measurements.counts_from_samples(samples)
+
+        return SimulationResult(
+            circuit=circuit,
+            final_state=state,
+            probabilities=probabilities,
+            shots=result_shots,
+            samples=samples,
+            counts=counts,
+        )
+

qomputing_simulator/examples/__init__.py

@@ -0,0 +1,2 @@
+
+

qomputing_simulator/examples/demo_circuits.py

@@ -0,0 +1,126 @@
+"""Sample circuits that can be executed with the state vector simulator.
+
+Examples included:
+  * Bell state (2 qubits)
+  * Deutsch-Jozsa (2 qubits, constant or balanced oracle)
+  * GHZ / Greenberger–Horne–Zeilinger (3 qubits)
+
+Run with:
+
+  python -m qomputing_simulator.examples.demo_circuits --example bell
+  python -m qomputing_simulator.examples.demo_circuits --example deutsch-jozsa --oracle balanced --shots 1024
+  python -m qomputing_simulator.examples.demo_circuits --example ghz --shots 1000 --seed 42
+"""
+
+from __future__ import annotations
+
+import argparse
+from typing import Callable, Dict
+
+import numpy as np
+
+from ..circuit import QuantumCircuit
+from ..simulator import StateVectorSimulator
+
+
+def build_bell_circuit() -> QuantumCircuit:
+    """Prepare the Bell state (|00> + |11>)/sqrt(2)."""
+    circuit = QuantumCircuit(2)
+    circuit.h(0).cx(0, 1)
+    return circuit
+
+
+def build_deutsch_jozsa_circuit(oracle: str) -> QuantumCircuit:
+    """Construct a two-qubit Deutsch–Jozsa circuit for the requested oracle."""
+    oracle = oracle.lower()
+    if oracle not in {"constant", "balanced"}:
+        raise ValueError("Deutsch–Jozsa oracle must be 'constant' or 'balanced'")
+
+    circuit = QuantumCircuit(2)
+    # Initialise |0>|1>
+    circuit.x(1)
+    # Create |+>|-> before the oracle.
+    circuit.h(0).h(1)
+
+    if oracle == "balanced":
+        # Oracle implements f(x) = x => CNOT
+        circuit.cx(0, 1)
+    else:
+        # Oracle implements f(x) = 0 => identity (no additional gates)
+        pass
+
+    # Interfere the first qubit to reveal the oracle type.
+    circuit.h(0)
+    return circuit
+
+
+def build_ghz_circuit() -> QuantumCircuit:
+    """Prepare a three-qubit GHZ state (|000> + |111>)/sqrt(2)."""
+    circuit = QuantumCircuit(3)
+    circuit.h(0).cx(0, 1).cx(1, 2)
+    return circuit
+
+
+def run_example(factory: Callable[[], QuantumCircuit], shots: int, seed: int | None) -> None:
+    circuit = factory()
+    simulator = StateVectorSimulator()
+    result = simulator.run(circuit, shots=shots if shots > 0 else None, seed=seed)
+
+    labels = [format(index, f"0{circuit.num_qubits}b") for index in range(2**circuit.num_qubits)]
+
+    print(f"Number of qubits: {circuit.num_qubits}")
+    print("Final state amplitudes:")
+    print(np.array2string(result.final_state, precision=6, suppress_small=True))
+
+    print("Measurement probabilities per computational basis state:")
+    for label, probability in zip(labels, result.probabilities):
+        if probability > 1e-6:
+            print(f"  P(|{label}⟩) = {probability:.6f}")
+
+    if result.counts:
+        print(f"\nSampled {result.shots} shots (seed={seed}):")
+        for bitstring, count in sorted(result.counts.items()):
+            print(f"  {bitstring}: {count} times")
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Run example circuits on the state vector simulator.")
+    parser.add_argument(
+        "--example",
+        type=str,
+        required=True,
+        choices=["bell", "deutsch-jozsa", "ghz"],
+        help="Which example circuit to run.",
+    )
+    parser.add_argument(
+        "--oracle",
+        type=str,
+        default="constant",
+        help="Oracle type for the Deutsch–Jozsa example (constant or balanced).",
+    )
+    parser.add_argument("--shots", type=int, default=0, help="Number of measurement shots to sample.")
+    parser.add_argument("--seed", type=int, default=None, help="Random seed for sampling.")
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+
+    example_builders: Dict[str, Callable[[], QuantumCircuit]] = {
+        "bell": build_bell_circuit,
+        "ghz": build_ghz_circuit,
+    }
+
+    if args.example == "deutsch-jozsa":
+        factory = lambda: build_deutsch_jozsa_circuit(args.oracle)  # noqa: E731
+    else:
+        factory = example_builders[args.example]
+
+    run_example(factory, shots=args.shots, seed=args.seed)
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())
+
+

qomputing_simulator/gates/__init__.py

@@ -0,0 +1,27 @@
+"""Gate registries and default gate sets."""
+
+from __future__ import annotations
+
+from .single_qubit import GATE_NAMES as SINGLE_QUBIT_NAMES
+from .single_qubit import HANDLERS as SINGLE_QUBIT_HANDLERS
+from .two_qubit import GATE_NAMES as TWO_QUBIT_NAMES
+from .two_qubit import HANDLERS as TWO_QUBIT_HANDLERS
+from .multi_qubit import GATE_NAMES as MULTI_QUBIT_NAMES
+from .multi_qubit import HANDLERS as MULTI_QUBIT_HANDLERS
+
+DEFAULT_SINGLE_QUBIT_GATES = ["h", "rx", "ry", "rz", "s", "t"]
+DEFAULT_TWO_QUBIT_GATES = ["cx", "cz", "swap"]
+DEFAULT_MULTI_QUBIT_GATES = []
+
+__all__ = [
+    "SINGLE_QUBIT_HANDLERS",
+    "TWO_QUBIT_HANDLERS",
+    "MULTI_QUBIT_HANDLERS",
+    "DEFAULT_SINGLE_QUBIT_GATES",
+    "DEFAULT_TWO_QUBIT_GATES",
+    "DEFAULT_MULTI_QUBIT_GATES",
+    "SINGLE_QUBIT_NAMES",
+    "TWO_QUBIT_NAMES",
+    "MULTI_QUBIT_NAMES",
+]
+

qomputing_simulator/gates/multi_qubit.py

@@ -0,0 +1,60 @@
+"""Multi-qubit (three or more qubits) gate implementations and registry."""
+
+from __future__ import annotations
+
+from typing import Callable, Dict, List
+
+import numpy as np
+
+from .. import linalg
+from ..circuit import Gate
+
+MultiQubitHandler = Callable[[np.ndarray, Gate, int, np.dtype], np.ndarray]
+
+
+def apply_ccx(state: np.ndarray, gate: Gate, num_qubits: int, dtype: np.dtype) -> np.ndarray:
+    if len(gate.controls) != 2 or len(gate.targets) != 1:
+        raise ValueError("ccx gate requires two controls and one target")
+    controls = list(gate.controls)
+    target = gate.targets[0]
+    matrix = np.eye(8, dtype=dtype)
+    matrix[6, 6] = 0
+    matrix[7, 7] = 0
+    matrix[6, 7] = 1
+    matrix[7, 6] = 1
+    return linalg.apply_unitary(state, [*controls, target], matrix, num_qubits)
+
+
+def apply_ccz(state: np.ndarray, gate: Gate, num_qubits: int, dtype: np.dtype) -> np.ndarray:
+    if len(gate.controls) != 2 or len(gate.targets) != 1:
+        raise ValueError("ccz gate requires two controls and one target")
+    controls = list(gate.controls)
+    target = gate.targets[0]
+    matrix = np.eye(8, dtype=dtype)
+    matrix[7, 7] = -1
+    return linalg.apply_unitary(state, [*controls, target], matrix, num_qubits)
+
+
+def apply_cswap(state: np.ndarray, gate: Gate, num_qubits: int, dtype: np.dtype) -> np.ndarray:
+    if len(gate.controls) != 1 or len(gate.targets) != 2:
+        raise ValueError("cswap gate requires one control and two targets")
+    control = gate.controls[0]
+    q1, q2 = gate.targets
+    matrix = np.eye(8, dtype=dtype)
+    matrix[5, 5] = 0
+    matrix[6, 6] = 0
+    matrix[5, 6] = 1
+    matrix[6, 5] = 1
+    return linalg.apply_unitary(state, [control, q1, q2], matrix, num_qubits)
+
+
+HANDLERS: Dict[str, MultiQubitHandler] = {
+    "ccx": apply_ccx,
+    "ccz": apply_ccz,
+    "cswap": apply_cswap,
+}
+
+GATE_NAMES: List[str] = list(HANDLERS.keys())
+
+__all__ = ["HANDLERS", "GATE_NAMES", "MultiQubitHandler"]
+

qomputing_simulator/gates/single_qubit.py

@@ -0,0 +1,204 @@
+"""Single-qubit gate implementations and registry."""
+
+from __future__ import annotations
+
+import cmath
+import math
+from typing import Callable, Dict, List
+
+import numpy as np
+
+from .. import linalg
+from ..circuit import Gate
+
+SingleQubitHandler = Callable[[np.ndarray, Gate, int, np.dtype], np.ndarray]
+
+
+def _apply_matrix(state: np.ndarray, gate: Gate, num_qubits: int, matrix: np.ndarray) -> np.ndarray:
+    if len(gate.targets) != 1:
+        raise ValueError(f"{gate.name} gate expects one target qubit")
+    target = gate.targets[0]
+    tensor = linalg.reshape_state(state, num_qubits)
+    axis = linalg.axis_for_qubit(target)
+    updated = np.tensordot(matrix, tensor, axes=([1], [axis]))
+    updated = np.moveaxis(updated, 0, axis)
+    return updated.reshape(state.shape)
+
+
+def apply_identity(state: np.ndarray, gate: Gate, num_qubits: int, dtype: np.dtype) -> np.ndarray:
+    return _apply_matrix(state, gate, num_qubits, np.eye(2, dtype=dtype))
+
+
+def apply_x(state: np.ndarray, gate: Gate, num_qubits: int, dtype: np.dtype) -> np.ndarray:
+    return _apply_matrix(state, gate, num_qubits, np.array([[0, 1], [1, 0]], dtype=dtype))
+
+
+def apply_y(state: np.ndarray, gate: Gate, num_qubits: int, dtype: np.dtype) -> np.ndarray:
+    return _apply_matrix(state, gate, num_qubits, np.array([[0, -1j], [1j, 0]], dtype=dtype))
+
+
+def apply_z(state: np.ndarray, gate: Gate, num_qubits: int, dtype: np.dtype) -> np.ndarray:
+    return _apply_matrix(state, gate, num_qubits, np.array([[1, 0], [0, -1]], dtype=dtype))
+
+
+def apply_h(state: np.ndarray, gate: Gate, num_qubits: int, dtype: np.dtype) -> np.ndarray:
+    return _apply_matrix(
+        state,
+        gate,
+        num_qubits,
+        (1 / math.sqrt(2)) * np.array([[1, 1], [1, -1]], dtype=dtype),
+    )
+
+
+def apply_s(state: np.ndarray, gate: Gate, num_qubits: int, dtype: np.dtype) -> np.ndarray:
+    return _apply_matrix(state, gate, num_qubits, np.array([[1, 0], [0, 1j]], dtype=dtype))
+
+
+def apply_sdg(state: np.ndarray, gate: Gate, num_qubits: int, dtype: np.dtype) -> np.ndarray:
+    return _apply_matrix(state, gate, num_qubits, np.array([[1, 0], [0, -1j]], dtype=dtype))
+
+
+def apply_t(state: np.ndarray, gate: Gate, num_qubits: int, dtype: np.dtype) -> np.ndarray:
+    return _apply_matrix(
+        state,
+        gate,
+        num_qubits,
+        np.array([[1, 0], [0, cmath.exp(1j * math.pi / 4)]], dtype=dtype),
+    )
+
+
+def apply_tdg(state: np.ndarray, gate: Gate, num_qubits: int, dtype: np.dtype) -> np.ndarray:
+    return _apply_matrix(
+        state,
+        gate,
+        num_qubits,
+        np.array([[1, 0], [0, cmath.exp(-1j * math.pi / 4)]], dtype=dtype),
+    )
+
+
+def apply_sx(state: np.ndarray, gate: Gate, num_qubits: int, dtype: np.dtype) -> np.ndarray:
+    matrix = 0.5 * np.array(
+        [
+            [1 + 1j, 1 - 1j],
+            [1 - 1j, 1 + 1j],
+        ],
+        dtype=dtype,
+    )
+    return _apply_matrix(state, gate, num_qubits, matrix)
+
+
+def apply_sxdg(state: np.ndarray, gate: Gate, num_qubits: int, dtype: np.dtype) -> np.ndarray:
+    matrix = 0.5 * np.array(
+        [
+            [1 - 1j, 1 + 1j],
+            [1 + 1j, 1 - 1j],
+        ],
+        dtype=dtype,
+    )
+    return _apply_matrix(state, gate, num_qubits, matrix)
+
+
+def apply_rx(state: np.ndarray, gate: Gate, num_qubits: int, dtype: np.dtype) -> np.ndarray:
+    theta = float(gate.params.get("theta", 0.0))
+    half = theta / 2.0
+    matrix = np.array(
+        [
+            [math.cos(half), -1j * math.sin(half)],
+            [-1j * math.sin(half), math.cos(half)],
+        ],
+        dtype=dtype,
+    )
+    return _apply_matrix(state, gate, num_qubits, matrix)
+
+
+def apply_ry(state: np.ndarray, gate: Gate, num_qubits: int, dtype: np.dtype) -> np.ndarray:
+    theta = float(gate.params.get("theta", 0.0))
+    half = theta / 2.0
+    matrix = np.array(
+        [
+            [math.cos(half), -math.sin(half)],
+            [math.sin(half), math.cos(half)],
+        ],
+        dtype=dtype,
+    )
+    return _apply_matrix(state, gate, num_qubits, matrix)
+
+
+def apply_rz(state: np.ndarray, gate: Gate, num_qubits: int, dtype: np.dtype) -> np.ndarray:
+    theta = float(gate.params.get("theta", 0.0))
+    half = theta / 2.0
+    matrix = np.array(
+        [
+            [cmath.exp(-1j * half), 0],
+            [0, cmath.exp(1j * half)],
+        ],
+        dtype=dtype,
+    )
+    return _apply_matrix(state, gate, num_qubits, matrix)
+
+
+def apply_u1(state: np.ndarray, gate: Gate, num_qubits: int, dtype: np.dtype) -> np.ndarray:
+    lam = float(gate.params.get("lambda", 0.0))
+    matrix = np.array(
+        [
+            [1.0, 0.0],
+            [0.0, cmath.exp(1j * lam)],
+        ],
+        dtype=dtype,
+    )
+    return _apply_matrix(state, gate, num_qubits, matrix)
+
+
+def apply_u2(state: np.ndarray, gate: Gate, num_qubits: int, dtype: np.dtype) -> np.ndarray:
+    phi = float(gate.params.get("phi", 0.0))
+    lam = float(gate.params.get("lambda", 0.0))
+    matrix = (1 / math.sqrt(2)) * np.array(
+        [
+            [1.0, -cmath.exp(1j * lam)],
+            [cmath.exp(1j * phi), cmath.exp(1j * (phi + lam))],
+        ],
+        dtype=dtype,
+    )
+    return _apply_matrix(state, gate, num_qubits, matrix)
+
+
+def apply_u3(state: np.ndarray, gate: Gate, num_qubits: int, dtype: np.dtype) -> np.ndarray:
+    theta = float(gate.params.get("theta", 0.0))
+    phi = float(gate.params.get("phi", 0.0))
+    lam = float(gate.params.get("lambda", 0.0))
+    cos = math.cos(theta / 2.0)
+    sin = math.sin(theta / 2.0)
+    matrix = np.array(
+        [
+            [cos, -cmath.exp(1j * lam) * sin],
+            [cmath.exp(1j * phi) * sin, cmath.exp(1j * (phi + lam)) * cos],
+        ],
+        dtype=dtype,
+    )
+    return _apply_matrix(state, gate, num_qubits, matrix)
+
+
+HANDLERS: Dict[str, SingleQubitHandler] = {
+    "id": apply_identity,
+    "x": apply_x,
+    "y": apply_y,
+    "z": apply_z,
+    "h": apply_h,
+    "s": apply_s,
+    "sdg": apply_sdg,
+    "t": apply_t,
+    "tdg": apply_tdg,
+    "sx": apply_sx,
+    "sxdg": apply_sxdg,
+    "rx": apply_rx,
+    "ry": apply_ry,
+    "rz": apply_rz,
+    "u1": apply_u1,
+    "u2": apply_u2,
+    "u3": apply_u3,
+}
+
+GATE_NAMES: List[str] = list(HANDLERS.keys())
+
+__all__ = ["HANDLERS", "GATE_NAMES", "SingleQubitHandler"]
+

qomputing_simulator/gates/two_qubit.py

@@ -0,0 +1,196 @@
+"""Two-qubit gate implementations and registry."""
+
+from __future__ import annotations
+
+import cmath
+import math
+from typing import Callable, Dict, List
+
+import numpy as np
+
+from .. import linalg
+from ..circuit import Gate
+
+TwoQubitHandler = Callable[[np.ndarray, Gate, int, np.dtype], np.ndarray]
+
+
+def _apply_unitary(state: np.ndarray, qubits: List[int], matrix: np.ndarray, num_qubits: int) -> np.ndarray:
+    return linalg.apply_unitary(state, qubits, matrix, num_qubits)
+
+
+def apply_cnot(state: np.ndarray, gate: Gate, num_qubits: int, dtype: np.dtype) -> np.ndarray:
+    if len(gate.controls) != 1 or len(gate.targets) != 1:
+        raise ValueError("cx gate requires one control and one target")
+    control = gate.controls[0]
+    target = gate.targets[0]
+    matrix = np.array(
+        [
+            [1, 0, 0, 0],
+            [0, 1, 0, 0],
+            [0, 0, 0, 1],
+            [0, 0, 1, 0],
+        ],
+        dtype=dtype,
+    )
+    return _apply_unitary(state, [control, target], matrix, num_qubits)
+
+
+def apply_cy(state: np.ndarray, gate: Gate, num_qubits: int, dtype: np.dtype) -> np.ndarray:
+    if len(gate.controls) != 1 or len(gate.targets) != 1:
+        raise ValueError("cy gate requires one control and one target")
+    control = gate.controls[0]
+    target = gate.targets[0]
+    matrix = np.array(
+        [
+            [1, 0, 0, 0],
+            [0, 1, 0, 0],
+            [0, 0, 0, -1j],
+            [0, 0, 1j, 0],
+        ],
+        dtype=dtype,
+    )
+    return _apply_unitary(state, [control, target], matrix, num_qubits)
+
+
+def apply_cz(state: np.ndarray, gate: Gate, num_qubits: int, dtype: np.dtype) -> np.ndarray:
+    if len(gate.controls) != 1 or len(gate.targets) != 1:
+        raise ValueError("cz gate requires one control and one target")
+    control = gate.controls[0]
+    target = gate.targets[0]
+    matrix = np.diag([1, 1, 1, -1]).astype(dtype)
+    return _apply_unitary(state, [control, target], matrix, num_qubits)
+
+
+def apply_cp(state: np.ndarray, gate: Gate, num_qubits: int, dtype: np.dtype) -> np.ndarray:
+    if len(gate.controls) != 1 or len(gate.targets) != 1:
+        raise ValueError("cp gate requires one control and one target")
+    phi = float(gate.params.get("phi", 0.0))
+    matrix = np.diag([1, 1, 1, cmath.exp(1j * phi)]).astype(dtype)
+    return _apply_unitary(state, [gate.controls[0], gate.targets[0]], matrix, num_qubits)
+
+
+def apply_swap(state: np.ndarray, gate: Gate, num_qubits: int, dtype: np.dtype) -> np.ndarray:
+    if len(gate.targets) != 2:
+        raise ValueError("swap gate requires two target qubits")
+    q1, q2 = gate.targets
+    matrix = np.array(
+        [
+            [1, 0, 0, 0],
+            [0, 0, 1, 0],
+            [0, 1, 0, 0],
+            [0, 0, 0, 1],
+        ],
+        dtype=dtype,
+    )
+    return _apply_unitary(state, [q1, q2], matrix, num_qubits)
+
+
+def apply_iswap(state: np.ndarray, gate: Gate, num_qubits: int, dtype: np.dtype) -> np.ndarray:
+    if len(gate.targets) != 2:
+        raise ValueError("iswap gate requires two target qubits")
+    q1, q2 = gate.targets
+    matrix = np.array(
+        [
+            [1, 0, 0, 0],
+            [0, 0, 1j, 0],
+            [0, 1j, 0, 0],
+            [0, 0, 0, 1],
+        ],
+        dtype=dtype,
+    )
+    return _apply_unitary(state, [q1, q2], matrix, num_qubits)
+
+
+def apply_sqrtiswap(state: np.ndarray, gate: Gate, num_qubits: int, dtype: np.dtype) -> np.ndarray:
+    if len(gate.targets) != 2:
+        raise ValueError("sqrtiswap gate requires two target qubits")
+    q1, q2 = gate.targets
+    matrix = np.array(
+        [
+            [1.0, 0.0, 0.0, 0.0],
+            [0.0, 0.5 + 0.5j, 0.5 - 0.5j, 0.0],
+            [0.0, 0.5 - 0.5j, 0.5 + 0.5j, 0.0],
+            [0.0, 0.0, 0.0, 1.0],
+        ],
+        dtype=dtype,
+    )
+    return _apply_unitary(state, [q1, q2], matrix, num_qubits)
+
+
+def _rotation_gate(pauli: np.ndarray, theta: float, dtype: np.dtype) -> np.ndarray:
+    half = theta / 2.0
+    return math.cos(half) * np.eye(4, dtype=dtype) - 1j * math.sin(half) * pauli
+
+
+def apply_rxx(state: np.ndarray, gate: Gate, num_qubits: int, dtype: np.dtype) -> np.ndarray:
+    if len(gate.targets) != 2:
+        raise ValueError("rxx gate requires two target qubits")
+    theta = float(gate.params.get("theta", 0.0))
+    pauli = np.kron(np.array([[0, 1], [1, 0]], dtype=dtype), np.array([[0, 1], [1, 0]], dtype=dtype))
+    matrix = _rotation_gate(pauli, theta, dtype)
+    return _apply_unitary(state, gate.targets, matrix, num_qubits)
+
+
+def apply_ryy(state: np.ndarray, gate: Gate, num_qubits: int, dtype: np.dtype) -> np.ndarray:
+    if len(gate.targets) != 2:
+        raise ValueError("ryy gate requires two target qubits")
+    theta = float(gate.params.get("theta", 0.0))
+    pauli = np.kron(
+        np.array([[0, -1j], [1j, 0]], dtype=dtype),
+        np.array([[0, -1j], [1j, 0]], dtype=dtype),
+    )
+    matrix = _rotation_gate(pauli, theta, dtype)
+    return _apply_unitary(state, gate.targets, matrix, num_qubits)
+
+
+def apply_rzz(state: np.ndarray, gate: Gate, num_qubits: int, dtype: np.dtype) -> np.ndarray:
+    if len(gate.targets) != 2:
+        raise ValueError("rzz gate requires two target qubits")
+    theta = float(gate.params.get("theta", 0.0))
+    pauli = np.kron(
+        np.array([[1, 0], [0, -1]], dtype=dtype),
+        np.array([[1, 0], [0, -1]], dtype=dtype),
+    )
+    matrix = _rotation_gate(pauli, theta, dtype)
+    return _apply_unitary(state, gate.targets, matrix, num_qubits)
+
+
+def apply_csx(state: np.ndarray, gate: Gate, num_qubits: int, dtype: np.dtype) -> np.ndarray:
+    if len(gate.controls) != 1 or len(gate.targets) != 1:
+        raise ValueError("csx gate requires one control and one target")
+    control = gate.controls[0]
+    target = gate.targets[0]
+    sx = 0.5 * np.array(
+        [
+            [1 + 1j, 1 - 1j],
+            [1 - 1j, 1 + 1j],
+        ],
+        dtype=dtype,
+    )
+    matrix = np.block(
+        [
+            [np.eye(2, dtype=dtype), np.zeros((2, 2), dtype=dtype)],
+            [np.zeros((2, 2), dtype=dtype), sx],
+        ]
+    )
+    return _apply_unitary(state, [control, target], matrix, num_qubits)
+
+
+HANDLERS: Dict[str, TwoQubitHandler] = {
+    "cx": apply_cnot,
+    "cy": apply_cy,
+    "cz": apply_cz,
+    "cp": apply_cp,
+    "swap": apply_swap,
+    "iswap": apply_iswap,
+    "sqrtiswap": apply_sqrtiswap,
+    "rxx": apply_rxx,
+    "ryy": apply_ryy,
+    "rzz": apply_rzz,
+    "csx": apply_csx,
+}
+
+GATE_NAMES: List[str] = list(HANDLERS.keys())
+
+__all__ = ["HANDLERS", "GATE_NAMES", "TwoQubitHandler"]
+