A qscommons project · version 1.1.1

qsengine, a quantum circuit simulator for Python

A Rust core runs your circuits on every CPU core or any GPU, up to 30 qubits. On a GPU it runs 22 qubits in 77 ms, and its docs start at bra-ket notation.

Get started Source on GitHub

PYbell.py1000 shots

import qsengine

qc = qsengine.QuantumCircuit(2)
qc.h(0)
qc.cx(0, 1)

print(qc.run(shots=1000, seed=1))
# {'00': 513, '11': 487}

print(qc.probabilities())
# 0.5 for 00, 0.5 for 11

print(qc)
# q0: ──H──●──
#          │
# q1: ─────X──

Only 00 and 11 come up: the qubits always agree.

Examples and their output

Build a circuit from gates in Python, then ask for counts or exact amplitudes. Every example in the documentation prints real output from qsengine 1.1.

Read the examples

Examples / Queued

BSBell stateh, cx · 2 qubitsQueued1000
GHGHZ stateh, cx, cx · 3 qubitsQueuedexact
RORotationry(π/3) · 1 qubitQueued1000
TPTeleportation3 qubits, 3 classical bitsQueued1000
DJDeutsch-Jozsaone oracle queryDoneexact
EVExpectationPauli strings ZZI and IZZDoneexact
MSMeasurementh, z, h · 1 qubitDoneexact
BLBloch sphererx(π/2) · 1 qubitDoneexact
BIBad inputcx(1, 1) · ValueErrorDonenone

PYbell.py PYghz.py 1000 shots

import qsengine

qc = qsengine.QuantumCircuit(2)
qc.h(0)
qc.cx(0, 1)

counts = qc.run(shots=1000, seed=1)
print(counts)
# {'00': 513, '11': 487}

print(qc.probabilities())
# 0.5 for 00, 0.5 for 11

print(qc)
# q0: ──H──●──
#          │
# q1: ─────X──

# the same circuit, each backend
cpu = qc.run(backend="cpu")
gpu = qc.run(backend="gpu")

# three qubits: a GHZ state
ghz = qsengine.QuantumCircuit(3)
ghz.h(0)
ghz.cx(0, 1)
ghz.cx(1, 2)
print(ghz.statevector())

Puts qubit 0 in an equal superposition.

How qsengine is tested and built. Checked against NumPy, benchmarked on GPUs, with sensible defaults and a one-line install.

Checks results against NumPy

Each gate and random circuit is compared with a plain NumPy reference simulator, on the CPU and the GPU.

qscommons/qsengine zsh main

~/qscommons/qsengine$pytest -q

4 of 4 checks

every_gate_against_numpycpu, gpupassed

random_circuits_against_numpycpu, gpupassed

expectation_against_numpycpu, gpupassed

teleportationcpu, gpupassed

ReferenceNumPy(float64)

Backendscpu, gpu(both)

Doneall passed

~/qscommons/qsengine$

Runs 22 qubits in 77 ms

On any vendor's GPU through Vulkan, DirectX 12 or Metal, 5.6 times faster than Qiskit Aer on the same circuit.

GPU time, 1000 shots 9 to 22 qubits

77 ms 5.6× faster than Qiskit Aer at 22

Picks the CPU or GPU for you

With backend="auto", small circuits run in 64-bit on every CPU core and large ones move to the GPU.

backend="auto"

3 of 4 on

GPU from 14 qubitsBelow that, every CPU core
Fall back to the CPUWhen no GPU or driver works
Mid-circuit runs on the CPUBelow 20 qubits
64-bit at every sizePass backend="cpu"

Installs with one command

One wheel per platform covers CPython 3.9 and newer, so there is nothing to compile and NumPy comes with it.

Your first circuit

2 of 5

pip install qsengine
import qsengine
Build a Bell state
Run 1000 shots
Read the counts

qsengine questions

What people ask before they install it.

Ask on GitHub

Does qsengine need a GPU?

No. qsengine runs on any CPU and uses a GPU when one is present, through Vulkan, DirectX 12 or Metal.

How large a circuit can qsengine run?

Up to 30 qubits. Memory doubles with every qubit: 20 qubits take 16 MiB and 30 take 16 GiB.

Which Python versions work?

CPython 3.9 and newer, with one wheel per platform.

How do I contribute?

Open an issue for a bug or an idea, or send a pull request. The contributing guide covers running the tests and updating the docs. Read the contributing guide