qomputing-simulator 0.1.0__py3-none-any.whl

qomputing_simulator/linalg.py

@@ -0,0 +1,62 @@
+"""Shared tensor and linear algebra helpers."""
+
+from __future__ import annotations
+
+from typing import Dict, List, Tuple
+
+import numpy as np
+
+
+def initial_state(num_qubits: int, *, dtype: np.dtype) -> np.ndarray:
+    size = 1 << num_qubits
+    state = np.zeros(size, dtype=dtype)
+    state[0] = 1.0 + 0j
+    return state
+
+
+def axis_for_qubit(qubit: int) -> int:
+    """Return tensor axis index for the given little-endian qubit."""
+    return -(qubit + 1)
+
+
+def reshape_state(state: np.ndarray, num_qubits: int) -> np.ndarray:
+    return state.reshape((2,) * num_qubits)
+
+
+def swap_axes(tensor: np.ndarray, axis_a: int, axis_b: int) -> np.ndarray:
+    return np.swapaxes(tensor, axis_a, axis_b)
+
+
+def select_indices(num_qubits: int, indices: Dict[int, int]) -> Tuple[slice, ...]:
+    slices = [slice(None)] * num_qubits
+    for axis, value in indices.items():
+        slices[axis] = value
+    return tuple(slices)
+
+
+def apply_unitary(
+    state: np.ndarray,
+    qubits: List[int],
+    matrix: np.ndarray,
+    num_qubits: int,
+) -> np.ndarray:
+    qubits = list(qubits)
+    if not qubits:
+        return state
+    matrix = np.asarray(matrix, dtype=state.dtype)
+    dimension = 1 << len(qubits)
+    if matrix.shape != (dimension, dimension):
+        raise ValueError("Unitary size does not match qubit count")
+
+    tensor = reshape_state(state, num_qubits)
+    axes = [axis_for_qubit(q) for q in qubits]
+    dest_axes = list(range(-len(qubits), 0))
+    tensor = np.moveaxis(tensor, axes, dest_axes)
+
+    leading_shape = tensor.shape[:-len(qubits)]
+    reshaped = tensor.reshape(-1, dimension).T
+    transformed = matrix @ reshaped
+    tensor = transformed.T.reshape(*leading_shape, *([2] * len(qubits)))
+    tensor = np.moveaxis(tensor, dest_axes, axes)
+    return tensor.reshape(state.shape)
+

qomputing_simulator/run.py

@@ -0,0 +1,85 @@
+"""High-level library API to run the state vector simulator."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Union
+
+from .circuit import QuantumCircuit
+from .circuit_builders import random_circuit
+from .simulator import SimulationResult, StateVectorSimulator
+from .xeb import LinearXEBResult, run_linear_xeb_experiment
+
+
+def load_circuit(path: Union[Path, str]) -> QuantumCircuit:
+    """Load a circuit from a JSON file.
+
+    Args:
+        path: Path to a JSON file with keys "num_qubits" and "gates".
+
+    Returns:
+        QuantumCircuit ready for run() or run_xeb().
+    """
+    path = Path(path)
+    with path.open("r", encoding="utf-8") as f:
+        payload = json.load(f)
+    return QuantumCircuit.from_dict(payload)
+
+
+def run(
+    circuit: Union[QuantumCircuit, Path, str],
+    shots: int = 0,
+    seed: int | None = None,
+    simulator: StateVectorSimulator | None = None,
+) -> SimulationResult:
+    """Run a circuit and return the simulation result.
+
+    Args:
+        circuit: A QuantumCircuit, or a path to a JSON circuit file.
+        shots: Number of measurement shots to sample (0 = state vector only, no sampling).
+        seed: Random seed for reproducible sampling.
+        simulator: Optional simulator instance; a new one is created if not provided.
+
+    Returns:
+        SimulationResult with final_state, probabilities, and (if shots > 0) samples and counts.
+    """
+    if not isinstance(circuit, QuantumCircuit):
+        circuit = load_circuit(circuit)
+    sim = simulator or StateVectorSimulator()
+    return sim.run(circuit, shots=shots, seed=seed)
+
+
+def run_xeb(
+    circuit: Union[QuantumCircuit, Path, str],
+    shots: int,
+    seed: int | None = None,
+    simulator: StateVectorSimulator | None = None,
+) -> LinearXEBResult:
+    """Run a linear XEB experiment: simulate the circuit, sample measurements, compute fidelity.
+
+    Args:
+        circuit: A QuantumCircuit, or a path to a JSON circuit file.
+        shots: Number of measurement shots (must be > 0).
+        seed: Random seed for reproducibility.
+        simulator: Optional simulator instance.
+
+    Returns:
+        LinearXEBResult with fidelity, samples, and sample_probabilities.
+    """
+    if not isinstance(circuit, QuantumCircuit):
+        circuit = load_circuit(circuit)
+    return run_linear_xeb_experiment(
+        circuit,
+        simulator=simulator,
+        shots=shots,
+        seed=seed,
+    )
+
+
+__all__ = [
+    "load_circuit",
+    "run",
+    "run_xeb",
+    "random_circuit",
+]

qomputing_simulator/simulator.py

@@ -0,0 +1,6 @@
+"""Backward-compatible shim exposing the simulation engine."""
+
+from .engine import SimulationResult, StateVectorSimulator
+
+__all__ = ["SimulationResult", "StateVectorSimulator"]
+

qomputing_simulator/xeb.py

@@ -0,0 +1,77 @@
+"""Cross-entropy benchmarking utilities."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict, Iterable, List, Optional
+
+from .circuit import QuantumCircuit
+from .simulator import StateVectorSimulator
+
+
+@dataclass
+class LinearXEBResult:
+    """Summary of a linear XEB experiment."""
+
+    circuit: QuantumCircuit
+    fidelity: float
+    shots: int
+    samples: List[str]
+    ideal_probabilities: List[float]
+    sample_probabilities: Dict[str, float]
+
+
+def compute_linear_xeb_fidelity(
+    ideal_probabilities: Iterable[float],
+    samples: Iterable[str],
+) -> float:
+    samples = list(samples)
+    if not samples:
+        raise ValueError("XEB fidelity requires at least one sample")
+
+    num_qubits = len(samples[0])
+    dimension = 1 << num_qubits
+
+    probs = list(ideal_probabilities)
+    if len(probs) != dimension:
+        raise ValueError("Ideal probability vector size does not match bitstring width")
+
+    prob_lookup = {format(index, f"0{num_qubits}b"): float(p) for index, p in enumerate(probs)}
+    average_p = sum(prob_lookup[bitstring] for bitstring in samples) / len(samples)
+    fidelity = dimension * average_p - 1.0
+    return fidelity
+
+
+def run_linear_xeb_experiment(
+    circuit: QuantumCircuit,
+    simulator: Optional[StateVectorSimulator] = None,
+    *,
+    shots: int,
+    seed: int | None = None,
+) -> LinearXEBResult:
+    if shots <= 0:
+        raise ValueError("XEB experiment requires shots > 0")
+    simulator = simulator or StateVectorSimulator()
+    result = simulator.run(circuit, shots=shots, seed=seed)
+    if result.samples is None:
+        raise RuntimeError("Simulator did not return measurement samples")
+    fidelity = compute_linear_xeb_fidelity(result.probabilities, result.samples)
+    sample_probabilities = _relative_frequencies(result.samples)
+    return LinearXEBResult(
+        circuit=circuit,
+        fidelity=fidelity,
+        shots=shots,
+        samples=result.samples,
+        ideal_probabilities=result.probabilities,
+        sample_probabilities=sample_probabilities,
+    )
+
+
+def _relative_frequencies(samples: Iterable[str]) -> Dict[str, float]:
+    counts: Dict[str, int] = {}
+    total = 0
+    for bitstring in samples:
+        counts[bitstring] = counts.get(bitstring, 0) + 1
+        total += 1
+    return {bitstring: count / total for bitstring, count in counts.items()}
+

qomputing_simulator-0.1.0.dist-info/METADATA

@@ -0,0 +1,314 @@
+Metadata-Version: 2.4
+Name: qomputing-simulator
+Version: 0.1.0
+Summary: Quantum computing state vector simulator with linear XEB benchmarking
+Author: Qomputing Simulator Maintainers
+License-Expression: MIT
+Keywords: quantum,simulation,state vector,xeb
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: numpy<3.0,>=1.24
+Requires-Dist: cirq<2.0,>=1.6
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Provides-Extra: build
+Requires-Dist: build>=1.0; extra == "build"
+
+# Qomputing Simulator
+
+Qomputing Simulator is a lightweight, pure Python toolkit for simulating quantum state vectors and running linear cross-entropy benchmarking (XEB) experiments end-to-end.
+
+**Will `pip install qomputing-simulator` work?**  
+- **Yes**, after you publish the package to [PyPI](https://pypi.org) (see “Publish to PyPI” below). Until then, pip won’t find it.
+- **Until then**, install from the repo: in the project folder run `pip install .`, or from anywhere run  
+  `pip install git+https://github.com/d2Anubis/state-vector-simulator.git`
+
+---
+
+## How people install (step-by-step)
+
+**If the package is on PyPI** (after you publish), users can do:
+
+1. **Install the package**
+   ```bash
+   pip install qomputing-simulator
+   ```
+
+2. **Use the CLI** (optional)
+   ```bash
+   qomputing-sim random-circuit --qubits 3 --depth 5 --shots 1000
+   qomputing-sim simulate --circuit path/to/circuit.json --shots 512
+   ```
+
+3. **Use it in Python**
+   ```python
+   from qomputing_simulator import run, QuantumCircuit, load_circuit, run_xeb, random_circuit
+
+   circuit = QuantumCircuit(2)
+   circuit.h(0).cx(0, 1)
+   result = run(circuit, shots=1000, seed=42)
+   print(result.counts)
+   ```
+
+**Optional:** Create a virtual environment first (recommended):
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install qomputing-simulator
+```
+
+**Optional extras:** `pip install qomputing-simulator[dev]` (adds pytest), `pip install qomputing-simulator[build]` (adds build tool).
+
+---
+
+## Where you push and how to publish (maintainer)
+
+### 1. Push code to GitHub (or GitLab, etc.)
+
+- **Where:** Your Git remote (e.g. GitHub).
+- Create a repo if needed, then from your project folder:
+
+  ```bash
+  git remote add origin https://github.com/YOUR_USERNAME/qomputing-simulator.git
+  git add .
+  git commit -m "Rename to qomputing-simulator"
+  git push -u origin main
+  ```
+
+**GitHub permission (browser redirect + passcode):** If `git push` asks for login, use GitHub’s web flow so you’re redirected to GitHub to approve:
+
+  ```bash
+  ./scripts/github-auth.sh
+  ```
+
+  That script uses the [GitHub CLI](https://cli.github.com/) (`gh`). It will open your browser → you log in on GitHub → GitHub shows a one-time code → you paste the code back in the terminal. After that, `git push origin main` works without a password.  
+  If you don’t have `gh`: install it (e.g. `brew install gh` on macOS), then run `./scripts/github-auth.sh` again.
+
+- People can clone and install from source: `git clone https://github.com/YOUR_USERNAME/qomputing-simulator.git` then `pip install .` in the repo.
+
+### 2. Publish to PyPI (so anyone can `pip install qomputing-simulator`)
+
+PyPI is the default place pip installs from. Steps:
+
+1. **Create accounts**
+   - [pypi.org](https://pypi.org/) (for real releases)
+   - [test.pypi.org](https://test.pypi.org/) (optional, for testing uploads)
+
+2. **Install build tools**
+   ```bash
+   pip install build twine
+   ```
+
+3. **Build the package**
+   ```bash
+   cd /path/to/simulator
+   python -m build
+   ```
+   This creates `dist/qomputing_simulator-0.1.0-py3-none-any.whl` and `dist/qomputing_simulator-0.1.0.tar.gz`.
+
+4. **Upload to Test PyPI (optional)**
+   ```bash
+   twine upload --repository testpypi dist/*
+   ```
+   When prompted, use your Test PyPI username and password (or token). Test install with:
+   `pip install --index-url https://test.pypi.org/simple/ qomputing-simulator`
+
+5. **Upload to PyPI (real release)**
+   ```bash
+   twine upload dist/*
+   ```
+   Use your PyPI username and password, or an [API token](https://pypi.org/manage/account/token/).
+
+6. **Later releases:** Bump `version` in `pyproject.toml`, run `python -m build` again, then `twine upload dist/*`. You cannot reuse the same version number on PyPI.
+
+After step 5, anyone can run `pip install qomputing-simulator` without cloning the repo.
+
+---
+
+## Quick Start (development / from source)
+
+### Install from source (development or local)
+
+```bash
+git clone https://github.com/YOUR_USERNAME/qomputing-simulator.git
+cd qomputing-simulator
+python3 -m venv .venv
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install --upgrade pip
+pip install -e ".[dev]"
+```
+
+- `pip install -e .` installs the simulator and Cirq; the optional `[dev]` extra adds `pytest`.
+- To install as a normal (non-editable) library: `pip install .` (no `-e`).
+
+### Build wheels only (for offline or custom install)
+
+From the project root:
+
+```bash
+pip install build
+python -m build
+```
+
+Install the wheel anywhere: `pip install dist/qomputing_simulator-0.1.0-py3-none-any.whl`
+
+### Offline / no wheel build
+
+If you cannot use pip to fetch the package:
+
+```bash
+export PYTHONPATH="$PWD"
+python -m qomputing_simulator.cli random-circuit --qubits 3 --depth 5 --shots 1000
+```
+
+## Repository Layout
+
+```
+qomputing_simulator/
+├── circuit.py            # QuantumCircuit builder, JSON (de)serialization
+├── gates/                # Single-, two-, and multi-qubit gate handlers
+├── engine/               # StateVectorSimulator core, result dataclass, sampling
+├── linalg.py             # Shared tensor/linear algebra helpers
+├── cli.py                # CLI entry point (`qomputing-sim`)
+├── xeb.py                # Linear XEB fidelity helpers
+├── tools/cirq_comparison.py  # Parity harness against Cirq
+└── tests/                # Pytest parity checks for representative gates
+```
+
+## CLI Usage
+
+- Run a random-circuit XEB benchmark:
+
+  ```bash
+  qomputing-sim random-circuit --qubits 3 --depth 5 --shots 1000
+  ```
+
+  Use `--single-qubit-gates/--two-qubit-gates/--multi-qubit-gates` to override the default gate pools (`["h","rx","ry","rz","s","t"]`, `["cx","cz","swap"]`, none).
+
+- Simulate a circuit defined in JSON:
+
+  ```bash
+  qomputing-sim simulate --circuit circuits/example.json --shots 512 --seed 123
+  ```
+
+## Library usage
+
+You can run the simulator from Python:
+
+```python
+from qomputing_simulator import (
+    QuantumCircuit,
+    load_circuit,
+    run,
+    run_xeb,
+    random_circuit,
+)
+
+# Build a circuit and run (state vector only if shots=0)
+circuit = QuantumCircuit(2)
+circuit.h(0).cx(0, 1)
+result = run(circuit, shots=1000, seed=42)
+print(result.final_state, result.probabilities, result.counts)
+
+# Load from JSON
+circuit = load_circuit("circuits/example.json")
+result = run(circuit, shots=512)
+
+# Random circuit and linear XEB
+circuit = random_circuit(num_qubits=3, depth=5, seed=7)
+xeb_result = run_xeb(circuit, shots=1000, seed=7)
+print(xeb_result.fidelity, xeb_result.sample_probabilities)
+```
+
+See `examples/library_usage.py` for a runnable example.
+
+## Example Circuits
+
+Ready-made demonstrations live in `qomputing_simulator/examples/demo_circuits.py`. After activating your environment, run them as a module from the project root:
+
+```bash
+python -m qomputing_simulator.examples.demo_circuits --example bell
+python -m qomputing_simulator.examples.demo_circuits --example deutsch-jozsa --oracle balanced --shots 1024 --seed 7
+python -m qomputing_simulator.examples.demo_circuits --example ghz --shots 1000 --seed 123
+```
+
+Each command prints the final state vector, measurement probabilities, and (when `--shots > 0`) sampled counts. Use `--example bell|deutsch-jozsa|ghz` and, for Deutsch–Jozsa, pick `--oracle constant|balanced`.
+
+## Circuit Specification
+
+Circuits are defined as JSON documents of the following structure:
+
+```json
+{
+  "num_qubits": 2,
+  "gates": [
+    {"name": "h", "targets": [0]},
+    {"name": "cx", "controls": [0], "targets": [1]},
+    {"name": "rz", "targets": [0], "params": {"theta": 1.5708}}
+  ]
+}
+```
+
+Supported gate names (and their parameters):
+
+- Single-qubit: `id`, `x`, `y`, `z`, `h`, `s`, `sdg`, `t`, `tdg`, `sx`, `sxdg`, `rx(θ)`, `ry(θ)`, `rz(θ)`, `u1(λ)`, `u2(φ,λ)`, `u3(θ,φ,λ)`
+- Two-qubit: `cx`, `cy`, `cz`, `cp(φ)`, `csx`, `swap`, `iswap`, `sqrtiswap`, `rxx(θ)`, `ryy(θ)`, `rzz(θ)`
+- Multi-qubit: `ccx`, `ccz`, `cswap`
+
+## Testing & Validation
+
+1. **Unit tests (Pytest)**
+
+   ```bash
+   pytest
+   ```
+
+   The tests execute representative single-, two-, and three-qubit circuits and assert that our simulator matches Cirq to ≤1e-7 after global phase alignment.
+
+2. **Parity harness against Cirq**
+
+   ```bash
+   export PYTHONPATH="$PWD"  # only needed if not pip-installed
+   python tools/cirq_comparison.py \
+     --min-qubits 1 --max-qubits 5 \
+     --depths 3 5 \
+     --circuits-per-config 3 \
+     --shots 256 \
+     --seed 7
+   ```
+
+   The summary at the end reports maximum amplitude/probability/XEB deviations. Pass `--help` to explore gate-pool overrides or larger qubit ranges. For qubits ≥20, allocate ample RAM (≥16 GB) and expect runtimes of multiple minutes.
+
+3. **Large-scale sweep (optional)**
+
+   ```bash
+   python tools/cirq_comparison.py \
+     --min-qubits 5 --max-qubits 25 \
+     --depths 5 \
+     --circuits-per-config 1 \
+     --shots 0 \
+     --seed 42 \
+     > comparison_results_25q.txt
+   ```
+
+   This tests state-vector parity without sampling. Inspect the resulting file for per-configuration error logs and the summary block.
+
+## Development Workflow
+
+- Run `pytest` before committing.
+- Use `qomputing-sim random-circuit` to generate sample workloads or JSONs for reproducible scenarios.
+- Benchmark changes with `tools/cirq_comparison.py` to confirm parity with Cirq remains within tolerance.
+- Generated artifacts (`comparison_results*.txt`, `__pycache__/`, virtual environments) are ignored via `.gitignore`.
+
+## License
+
+MIT
+

qomputing_simulator-0.1.0.dist-info/RECORD

@@ -0,0 +1,27 @@
+examples/library_usage.py,sha256=9E8NZWo7LXJsAOwBcXaDZVAemFD3Rou7VhSH2xr73wc,925
+qomputing_simulator/__init__.py,sha256=F-qleLgIba0I4wKurAM8sgwvsVSvxsqBUu9XF3c5omM,568
+qomputing_simulator/circuit.py,sha256=K2Mx7KDfD-rTEx_nslG9AJ78jZtpfcu1C9BN95pDzpc,8959
+qomputing_simulator/circuit_builders.py,sha256=RZ5iT95FaWqom_Qm1iHPTCP9wYaVzkR6OTlhmoAHv3U,6234
+qomputing_simulator/cli.py,sha256=RronVNZqUchDdgitXrI6YKfps012oH-JwISe39oYkcs,4047
+qomputing_simulator/linalg.py,sha256=BeJldEZ-d_KUGKNONSofj3MOq0rxsT3eTCrvx2D3oBQ,1793
+qomputing_simulator/run.py,sha256=ubLZYpFDPaRYIOLEaE2ayEXaZJq_hyA3vqTc3vbiNik,2530
+qomputing_simulator/simulator.py,sha256=ZOtbHALrwdKlfte_lN_QFDLD514uxEElfUM1vqX-E8Y,180
+qomputing_simulator/xeb.py,sha256=RdQdfOyHShhHvXLuFf_F6sUKY0yLiJ11DYcG958yloA,2378
+qomputing_simulator/engine/__init__.py,sha256=IELlRtL7sGCVv600o1sJ5LBMMoryZhJ8Y65i9xh5MFw,179
+qomputing_simulator/engine/measurements.py,sha256=SPDCw0XT7pbb4vRlo8ZgAWWjcs0rVh_Q5SGeh6-09Jw,698
+qomputing_simulator/engine/registry.py,sha256=F6BYAh7pOCWpRx83AgtWldjLS4bKQXGN8e66UriZ3eo,871
+qomputing_simulator/engine/result.py,sha256=wXNvPIR73EGJvGg3okkyONo9Yo63BdjDodxqzzg6Dlo,857
+qomputing_simulator/engine/statevector.py,sha256=fMscMx-HRmtIsdqCvunFTc9F2LWaaKmn9hT3LgeSv1c,1510
+qomputing_simulator/examples/__init__.py,sha256=daEdpEyAJIa8b2VkCqSKcw8PaExcB6Qro80XNes_sHA,2
+qomputing_simulator/examples/demo_circuits.py,sha256=YZQx5F58XJrKRmho8CQILtsGoGlI8Rrxww2LujpLVTA,4021
+qomputing_simulator/gates/__init__.py,sha256=oCMKx4LQw51luGZUJcIPZooZ1-A002DPR6Z3fKbP1Dc,836
+qomputing_simulator/gates/multi_qubit.py,sha256=PFUEqOhPbRlYYEuTZ8VxNJVKBNmcL7DqsG0-TklG2QA,1933
+qomputing_simulator/gates/single_qubit.py,sha256=gPQSNfKXk7--QU3lj8jAVPDLnW6rMkMx6RB4CN1CqQI,6213
+qomputing_simulator/gates/two_qubit.py,sha256=ud7eC3UonLiMBlP4jItC6DZfycffmqsW4yDmp_nBkLA,6505
+tests/test_parity.py,sha256=Gj62r_9k5v8YvLnis0558oz6nswmVHXfmtf9q6a0JJE,4225
+tools/cirq_comparison.py,sha256=Pd611E4k6dF2avp3q1uZGN7Svp4xJtmo6OvGKFNtg0Y,15217
+qomputing_simulator-0.1.0.dist-info/METADATA,sha256=OyAMitN9FHKiowdnS2_e23yTQ_BWwj97bOkpaundJjg,10411
+qomputing_simulator-0.1.0.dist-info/WHEEL,sha256=YLJXdYXQ2FQ0Uqn2J-6iEIC-3iOey8lH3xCtvFLkd8Q,91
+qomputing_simulator-0.1.0.dist-info/entry_points.txt,sha256=Zh1QINR7M1e4WDAR_kHLcIWLRR4sj81hb-C8BIgNRW4,63
+qomputing_simulator-0.1.0.dist-info/top_level.txt,sha256=Rz0CNs42KK3erTfrENj93ujTb3GxuKz0dEBZHsywAlI,41
+qomputing_simulator-0.1.0.dist-info/RECORD,,

qomputing_simulator-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (81.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

qomputing_simulator-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+qomputing-sim = qomputing_simulator.cli:main

qomputing_simulator-0.1.0.dist-info/top_level.txt

@@ -0,0 +1,4 @@
+examples
+qomputing_simulator
+tests
+tools