Metadata-Version: 2.4
Name: macquerel
Version: 0.2.1
Summary: Quantum state-vector simulator for Apple Silicon
Project-URL: Homepage, https://github.com/guenp/macquerel
Project-URL: Documentation, https://guenp.github.io/macquerel/
Project-URL: Repository, https://github.com/guenp/macquerel
Project-URL: Changelog, https://github.com/guenp/macquerel/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/guenp/macquerel/issues
Author-email: Guen Prawiroatmodjo <4041805+guenp@users.noreply.github.com>
License-Expression: MIT
License-File: LICENSE
Keywords: apple-silicon,metal,mlx,quantum,simulator,statevector
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.11
Requires-Dist: numpy>=1.24
Provides-Extra: aer
Requires-Dist: qiskit-aer>=0.14; extra == 'aer'
Requires-Dist: qiskit>=1.0; extra == 'aer'
Provides-Extra: bench
Requires-Dist: matplotlib>=3.7; extra == 'bench'
Requires-Dist: qiskit-aer>=0.14; extra == 'bench'
Requires-Dist: qiskit>=1.0; extra == 'bench'
Requires-Dist: qulacs>=0.6; (python_version < '3.14') and extra == 'bench'
Provides-Extra: cirq
Requires-Dist: cirq-core>=1.3; extra == 'cirq'
Provides-Extra: metal
Requires-Dist: pyobjc-framework-metal>=10.0; extra == 'metal'
Provides-Extra: mlx
Requires-Dist: mlx>=0.3.0; extra == 'mlx'
Provides-Extra: qiskit
Requires-Dist: qiskit>=1.0; extra == 'qiskit'
Provides-Extra: qulacs
Requires-Dist: qulacs>=0.6; (python_version < '3.14') and extra == 'qulacs'
Provides-Extra: viz
Requires-Dist: matplotlib>=3.7; extra == 'viz'
Description-Content-Type: text/markdown

# macquerel

<img src="https://raw.githubusercontent.com/guenp/macquerel/main/logo.png" width="200" />

A quantum state-vector simulator targeting Apple Silicon's unified-memory architecture.

## Features

- **CPU backend** — pure NumPy reference implementation using the tensordot reshape trick
- **MLX backend** — Apple Silicon GPU acceleration via [MLX](https://ml-explore.github.io/mlx/), with graceful fallback on other platforms
- **Gate fusion compiler** — greedy left-to-right fusion of adjacent gates (up to 4 qubits) into composite unitaries
- **Gate classification** — automatically classifies gates as `diagonal`, `permutation`, or `dense` for optimized dispatch
- **Full gate library** — I, H, X, Y, Z, S, T, Rx, Ry, Rz, P, CNOT, CZ, SWAP, CP

## Installation

Requires Python 3.11+.

```bash
uv sync
```

To enable the MLX backend on Apple Silicon:

```bash
uv sync --extra mlx
```

## Usage

```python
from macquerel import Circuit, Simulator

# Bell state
circuit = Circuit(2)
circuit.h(0).cx(0, 1).measure_all()

sim = Simulator()               # defaults to CPU backend
counts = sim.run(circuit, shots=1000)
print(counts)  # Counter({'00': ~500, '11': ~500})
```

```python
# Statevector (no measurement)
circuit = Circuit(2)
circuit.h(0).cx(0, 1)

sv = sim.statevector(circuit)
print(sv)  # [0.707+0j, 0+0j, 0+0j, 0.707+0j]
```

```python
# Apple Silicon GPU backend
sim = Simulator(backend="mlx")
```

### Available gates

| Method | Gate |
|---|---|
| `.h(q)` | Hadamard |
| `.x(q)` / `.y(q)` / `.z(q)` | Pauli X/Y/Z |
| `.s(q)` / `.t(q)` | S / T phase |
| `.rx(q, θ)` / `.ry(q, θ)` / `.rz(q, θ)` | Rotation gates |
| `.p(q, λ)` | Phase gate |
| `.cx(ctrl, tgt)` | CNOT |
| `.cz(ctrl, tgt)` | Controlled-Z |
| `.swap(q0, q1)` | SWAP |
| `.cp(ctrl, tgt, λ)` | Controlled-Phase |
| `.measure(qubits)` / `.measure_all()` | Measurement |

Builders return `self` for chaining.

## Architecture

```
macquerel/
├── gates.py         # Gate matrices + classify()
├── circuit.py       # Circuit / Gate / MeasureOp dataclasses
├── compiler.py      # Gate fusion (fuse_gates)
├── simulator.py     # Simulator — statevector() and run()
└── backends/
    ├── cpu.py       # NumPy backend
    └── mlx_backend.py  # MLX backend (Apple Silicon)
```

## Running tests

```bash
uv run pytest
```

MLX backend tests are automatically skipped when MLX is not installed.

## Benchmarks

Quick smoke run (completes in a few seconds):

```bash
uv run python benchmarks/bench_versions.py --versions latest --backends cpu --qubits 6 8 --depth 8 --reps 1
```

Full benchmark commands:

```bash
# Install plotting and framework-comparison dependencies first.
uv sync --extra bench

# On Apple Silicon, include macquerel's optional GPU backends too:
uv sync --extra bench --extra mlx --extra metal

# macquerel CPU/MLX/Metal vs Qiskit Aer and Qulacs
uv run python benchmarks/bench_statevector.py \
  --json benchmarks/data/framework_comparison.json \
  --plot benchmarks/data/framework_comparison.png

# Fusion-width sweep
uv run python benchmarks/bench_fusion_width.py \
  --json benchmarks/data/fusion_width.json \
  --plot benchmarks/data/fusion_width.png

# Released-version regression comparison for CPU/MLX/Metal
uv run python benchmarks/bench_versions.py \
  --versions latest --json benchmarks/data/version_regression.json \
  --plot benchmarks/data/version_regression.png
```

The framework benchmark prints every backend it discovers at startup. Optional frameworks and
Apple-only backends are reported as skipped when they are unavailable. Qulacs currently may
need a Python version with a prebuilt wheel, or local C++/Boost build prerequisites.

## Requirements

- Python ≥ 3.11
- numpy ≥ 1.24
- mlx ≥ 0.3.0 *(optional, Apple Silicon only)*
