Getting Started

Welcome. This page gets you from zero to a running quantum circuit with gradients.

1. Install

pip install superfermion

That's it. Python 3.10–3.13 on Linux, macOS, or Windows. Pre-built wheels for all three platforms — no Rust toolchain required.

Optional extras

pip install "superfermion[all]"        # everything
pip install "superfermion[qml]"        # JAX + Flax + Optax
pip install "superfermion[chemistry]"  # PySCF for molecular simulation
pip install "superfermion[qpu]"        # IBM + AWS Braket SDKs
pip install "superfermion[ml]"         # PyTorch + TensorFlow + Cirq

2. Verify

import superfermion as sf
print(sf.__version__)  # 0.1.0

3. Build a circuit

import superfermion as sf

# Bell state: entangle two qubits
qc = sf.Circuit(2).h(0).cx(0, 1)
print(qc.draw())
# q0: ── H ── ● ──
# q1: ────── X ──

Every gate method returns the circuit — chain as many as you want.

4. Run it

result = sf.run(qc, shots=1024)
print(result.counts)  # {'00': ~512, '11': ~512}

sf.run() works everywhere — local CPU, GPU, IBM Quantum, IonQ. Same API.

5. Get the quantum state

state = sf.simulate(qc)       # returns sf.State (Rust-native)
print(state.numpy())           # [0.707+0j, 0, 0, 0.707+0j]
print(state.entropy())         # 0.0
print(state.purity())          # 1.0

sf.State lives in Rust. All methods — expectation(), grad(), sample() — dispatch to compiled Rust.

6. Compute an expectation value

from superfermion import Hamiltonian, PauliString

H = Hamiltonian([PauliString("ZZ", coeff=1.0)])
energy = state.expectation(H.to_sparse_list())
print(energy)  # 1.0

7. Take a gradient

theta = sf.param("theta")
qc = sf.Circuit(1).ry(theta, 0)

state = sf.simulate(qc, params={"theta": 0.5})
obs = [([3], 1.0, 0.0)]      # Pauli Z
dag = qc.bind({"theta": 0.5}).to_ir()
grads = state.grad(obs, dag, {"theta": 0.5})

print(grads)  # {"theta": -0.479...}

The adjoint method computes gradients in one backward pass regardless of parameter count. Up to 800x faster than parameter-shift for deep circuits.

8. Try a different simulation method

# MPS — for weakly entangled circuits, scales to 200+ qubits
result = sf.run(qc, method="mps", bond_dim=64, shots=1024)

# Stabilizer — for Clifford-only circuits, scales to 1000+ qubits
result = sf.run(qc, method="stabilizer", shots=1024)

# Density matrix — for noisy simulation
noise = sf.NoiseModel().add_depolarizing(0.01)
result = sf.run(qc, method="density_matrix", noise_model=noise, shots=0)

Where next

Now that you've run your first circuit, dive into the guides:

Building Circuits — every gate, parameterized circuits, circuit properties
Running Simulations — devices, methods, noise, results
Gradients & VQE — 5 gradient methods, VQE optimization
Hardware Compilation — gate optimization, qubit routing
API Reference — every class and method

From source (development)

git clone https://github.com/Catstate101/superfermion.git
cd superfermion
pip install maturin
cd crates/sf-bindings && maturin develop --release && cd ../..
pip install -e ".[dev]"

On this page