state-vector-simulator 0.1.0
State vector simulator with linear XEB benchmarking
License: MIT
Requires Python: >=3.9
Keywords: quantum, simulation, state vector, xeb

# State Vector Simulator

State Vector Simulator is a lightweight, pure Python toolkit for simulating quantum state vectors and running linear cross-entropy benchmarking (XEB) experiments end-to-end.

## Quick Start

### Install from source (development or local)

```bash
git clone https://github.com/d2Anubis/state-vector-simulator.git
cd state-vector-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`).

### Install as a pip package (from PyPI, after you publish)

Once the package is published to [PyPI](https://pypi.org/), anyone can install it with:

```bash
pip install state-vector-simulator
```

Optional extras:

```bash
pip install state-vector-simulator[dev]   # adds pytest
pip install state-vector-simulator[build] # adds build tool for creating wheels
```

### Build distributable wheels (for publishing or offline install)

From the project root:

```bash
pip install build
python -m build
```

This creates `dist/state_vector_simulator-0.1.0-py3-none-any.whl` and a source tarball. Install the wheel anywhere with:

```bash
pip install dist/state_vector_simulator-0.1.0-py3-none-any.whl
```

### Publishing to PyPI

1. Create an account on [pypi.org](https://pypi.org/) and [test.pypi.org](https://test.pypi.org/) (for testing).
2. Install twine: `pip install twine`.
3. Build: `python -m build`.
4. Upload to Test PyPI: `twine upload --repository testpypi dist/*`.
5. Upload to PyPI: `twine upload dist/*` (use your PyPI token or username/password).

After that, users can run `pip install state-vector-simulator` from any machine.

### Offline / no wheel build

If you cannot compile wheels (offline environment), export the package on `PYTHONPATH` and call the CLI module directly:

```bash
export PYTHONPATH="$PWD/state_vector_simulator"
python -m state_vector_simulator.cli random-circuit --qubits 3 --depth 5 --shots 1000
```

## Repository Layout

```
state_vector_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 (`state-vector-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
  state-vector-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
  state-vector-sim simulate --circuit circuits/example.json --shots 512 --seed 123
  ```

## Library usage

You can run the simulator from Python:

```python
from state_vector_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 `state_vector_simulator/examples/demo_circuits.py`. After activating your environment, run them as a module from the project root:

```bash
python -m state_vector_simulator.examples.demo_circuits --example bell
python -m state_vector_simulator.examples.demo_circuits --example deutsch-jozsa --oracle balanced --shots 1024 --seed 7
python -m state_vector_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/state_vector_simulator"  # 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 `state-vector-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