MettleQ
Open-source quantum simulation · Python / MLX / Metal

Simulation you can inspect.

MettleQ is a local quantum-circuit simulator for Apple Silicon with exact statevectors, bounded matrix-product states, Qiskit and PennyLane adapters, memory preflight, explicit execution plans, and frozen benchmark evidence.

Start with MettleQRead the repository ↗
01

Install once. Measure honestly.

The accelerated path targets macOS arm64. Other platforms can still use the package’s MLX-independent drawing, QASM, and documentation utilities.

Recommended SDK install
python -m pip install "mettleq[sdk]"
Development install
git clone https://github.com/MonitSharma/MettleQ.git
cd MettleQ
python -m pip install -e ".[dev,sdk]"
Platform requirement. Full MLX/Metal simulation requires an Apple Silicon Mac. Adaptive execution chooses one measured numerical path; CPU and GPU timings are never added together into a synthetic speedup.
02

Use the front end you already know.

Both native SDK adapters preserve their result contracts and expose adaptive CPU/GPU selection.

Qiskit BackendV2
from qiskit import QuantumCircuit, transpile
from mettleq.integrations.qiskit import AdaptiveQiskitBackend

backend = AdaptiveQiskitBackend(precision="single")
circuit = QuantumCircuit(2, 2)
circuit.h(0)
circuit.cx(0, 1)
circuit.measure([0, 1], [0, 1])
result = backend.run(
    transpile(circuit, backend), shots=1000,
    seed_simulator=7,
).result()
print(result.get_counts())
PennyLane device
import pennylane as qml

dev = qml.device("mettleq.adaptive", wires=2,
                 precision="single")

@qml.qnode(dev)
def bell():
    qml.Hadamard(0)
    qml.CNOT(wires=[0, 1])
    return qml.expval(qml.Z(0) @ qml.Z(1))

print(bell())
03

Simulation methods and trade-offs.

Statevectors, matrix-product states, and adaptive execution solve different kinds of workloads. MettleQ reports which method ran, why it was selected, and what approximation or memory limits apply.

Exact

Statevector

Dense amplitudes, capability-probed Metal kernels, memory preflight, and phase-aligned parity validation.

Bounded approximation

Forward MPS

CPU-native tensor network with bond caps, recoverable SVDs, persistent routing, truncation evidence, and convergence checks.

Opt-in research path

Midpoint-MPO

Separate approximation contract and isolated worker environment for peaked-circuit experiments.

Adaptive policy

One measured path

Small work and double precision can remain on Aer or Lightning CPU. Larger exact statevector workloads move to Metal only when the measured crossover, memory model, output contract, and hardware capability all agree.

Trust boundary

Safety refusals

A preflight refusal is reported as a result. A circuit that violates the conservative memory envelope is not launched.

04

Results on the reference hardware.

Apple M3 Pro · 12 CPU cores · 18 integrated GPU cores · 36 GB unified memory · macOS arm64 · MLX 0.32 · Qiskit Aer 0.17.2 · PennyLane Lightning 0.45.

CPU baselines

Complete full-state runtimes on the M3 Pro CPU. Lower is better.

QubitsAer CPULightning CPU
163.760 ms9.003 ms
1812.608 ms46.538 ms
2047.574 ms118.461 ms
24687.554 ms2,027.497 ms
285,833.566 ms35,927.705 ms
2914,252.833 ms74,375.386 ms

MettleQ Metal runtimes

The same circuits through each SDK adapter on the integrated Apple GPU.

QubitsQiskit adapterPennyLane adapterWorst error
1614.728 ms6.233 ms3.75e−7
1820.119 ms12.543 ms3.98e−7
2035.859 ms10.675 ms4.02e−7
24150.980 ms108.346 ms1.99e−7
282,059.440 ms1,696.528 ms1.22e−7
295,203.575 ms4,646.928 ms1.33e−7
20qFirst width where MettleQ beats Aer CPU
16qFirst width where MettleQ beats Lightning CPU
≤ 5e−6Required phase-aligned accuracy gate

CPU and GPU measurements are shown separately. The crossover statements compare complete end-to-end calls for the same circuit and full-state output contract.

Line chart comparing MettleQ Apple GPU against Qiskit Aer and PennyLane Lightning across 16 to 29 qubits
Same-Mac CPU/GPU crossover. Every accepted row passed the global phase-aligned accuracy gate.
Comparison plot of radix-16 Metal optimization runtimes
Radix-16 statevector optimization on the same M3 Pro.
SDK method matrix comparison plot
SDK method matrix: exact statevector, MPS, and CPU reference paths.
05

Apple versus NVIDIA, honestly.

The cross-hardware campaign matched workloads at 15, 20, 24, 26, and 28 qubits. CUDA-Q remains faster on several high-width bandwidth-dominated cases.

Workload at 28qMettleQ Metal · M3 ProCUDA-Q · RTX 3070Lightning GPU · RTX 3070Aer CPU · WSL
QFT877.90 ms340.38 ms6,635.45 ms13,860.52 ms
Ring QAOA · 6 layers2,428.86 ms463.80 ms7,254.50 ms17,438.65 ms
GHZ341.94 ms173.24 ms1,141.82 ms3,332.40 ms
Grover proxy982.80 ms165.94 ms4,350.20 ms3,001.91 ms
Phase estimation2,391.85 ms363.80 ms6,881.60 ms16,894.65 ms
TFIM · 20 steps7,695.88 ms1,565.92 ms27,163.63 ms54,528.06 ms
Matched-width scaling plot comparing Apple MettleQ Metal with CUDA-Q on an RTX 3070
Matched-width cross-hardware scaling. Lower runtime is better; the two machines have different memory systems and software stacks.
What this means. MettleQ wins the Apple crossover and beats Lightning GPU across the published matched widths, but CUDA-Q’s specialized NVIDIA backend is faster at several 28-qubit endpoints. The result is a hardware-specific map, not a universal ranking.
06

MPS: the improvement is real, the limits matter.

The production MPS path in main is newer than the agent branch: it retains the native CPU core, persistent logical routing, native readout, and direct single-gate updates. The branch’s older rewrite would remove those paths, so only its safe regression tests were extracted.

WorkloadMettleQ routedMettleQ restoreMettleQ native tensorsAer CPU MPSRouted / Aer
GHZ · 1,000q d1338.76 ms338.28 ms797.22 ms57.90 ms0.17×
Line · 100q d8153.25 ms154.50 ms514.20 ms29.00 ms0.19×
Grid · 36q d2249.91 ms248.75 ms522.18 ms422.57 ms1.69×
Rainbow · 32q d1710.44 ms888.97 ms1,255.08 ms3.65 ms0.005×
Random long range · 32q d1264.76 ms376.30 ms544.00 ms3.40 ms0.013×
All-to-all · 20q d1851.13 ms4,700.62 ms1,422.03 ms25.17 ms0.030×

MPS results are contract-sensitive. Aer is still substantially faster on several CPU-MPS families; the MettleQ win on the 36q grid is a useful measured result, not a claim of blanket superiority.

MPS bond dimension convergence plot
Convergence evidence across bond dimensions.
Statevector memory policy plot
Memory-policy evidence and conservative preflight behavior.
07

Run it. Test it. Read the evidence.

The repository is the canonical source for raw runs, manifests, tutorials, and release checks. The website is an index and explanation, not a replacement for the data.

Local verification
python -m pip install -e ".[dev,tests]"
pytest -q
python -m build
python -m twine check dist/*

# Apple Silicon simulator + SDK + tutorial suite
./test.sh
python tools/run_tutorial_notebooks.py --no-write
Release checklist. Before publishing a stable package, test-upload to TestPyPI, scan reachable Git history for secrets and private artifacts, enable branch protection and secret scanning, then tag a clean release commit.