Superfermion

A high-performance quantum computing framework with a Python API and a Rust simulation core. Statevector, MPS, stabilizer, and density matrix simulation methods with native adjoint differentiation, quantum error correction, and multi-framework interop.

What is Superfermion?

Superfermion is a quantum computing framework that combines a Python-native API with a Rust acceleration core (Rayon multithreading + in-place statevector).

• 4 simulation methods — statevector (CPU/GPU), MPS tensor network, stabilizer (Aaronson-Gottesman tableau), density matrix (Kraus channels)
• Adjoint differentiation — 1 forward + 1 backward pass regardless of parameter count (44–198x faster than parameter-shift on deep circuits)
• MPS tensor networks — Rust MPS with faer-based QR decomposition and lazy SWAP routing; scales to 200+ qubits for low-entanglement circuits
• Stabilizer simulator — word-packed tableau; Clifford circuits at poly-time to ~1000 qubits
• Quantum Error Correction — stabilizer code constructions (Repetition, Shor, Steane, Surface) + decoders (BP+OSD, greedy matching, Union-Find, Neural); additional codes in progress
• Multi-framework ML — QuantumLayer (Flax), TorchQuantumLayer (PyTorch), TFQuantumLayer (TensorFlow)
• 5 gradient methods — adjoint, parameter-shift, SPSA, QNG, Riemannian
• Quantum algorithms — VQE, QAOA, Grover, QPE, HHL, Amplitude Estimation
• Chemistry module — Jordan-Wigner + Bravyi-Kitaev transformations, UCCSD ansatz, PySCF bridge, molecular Hamiltonian library
• Hardware compilation — gate decomposition, rotation merging, SABRE qubit routing, Pauli twirling; targets IBM, Rigetti, IonQ, IQM
• QPU providers — IBM Quantum, IonQ, AWS Braket, OpenQuantum
• Cross-framework bridges — Qiskit, Cirq, PennyLane, OpenQASM 2/3

Installation

pip install superfermion

Already installed? pip will not move an existing environment on its own, so upgrade in place:

pip install -U superfermion

From 0.1.20 the package also prints a one-line notice to stderr when a newer release is on PyPI. It checks at most once a day, in a background thread, and is silent when offline, in CI, or under pytest; disable it with SF_NO_UPDATE_CHECK=1.

Wheels are built once against the CPython stable ABI and tagged cp310-abi3, so a single binary per platform installs on CPython 3.10 and every later release, including versions published after the wheel was built:

Anything not covered by a wheel — PyPy, 32-bit targets, other architectures, and free-threaded builds (3.14t, 3.15t) — is built from the source distribution by pip, which needs Rust 1.85+ and ~3 GB of free disk. Free-threaded interpreters get a version-specific extension instead of a limited-API one; prebuilt free-threaded wheels are not published yet.

From source (development)

git clone https://github.com/Catstate101/superfermion.git
cd superfermion
pip install maturin
maturin develop --release        # builds crates/sf-bindings into the source tree
pip install -e ".[dev]"

Requirements: Python 3.10+, Rust 1.85+, ~3 GB free disk for the Rust build.

Optional dependency groups:

pip install -e ".[dev]"        # pytest, ruff, mypy, black
pip install -e ".[gpu]"        # JAX with CUDA 12
pip install -e ".[qpu]"        # IBM + AWS Braket SDKs
pip install -e ".[benchmarks]" # PennyLane, Qiskit Aer, pandas, matplotlib
pip install -e ".[chemistry]"  # PySCF, SciPy
pip install -e ".[viz]"        # matplotlib
pip install -e ".[all]"        # everything

Quick Start

import superfermion as sf

# Bell state
qc = sf.Circuit(2).h(0).cx(0, 1)
result = sf.run(qc, device="cpu", shots=1024)
print(result.counts)  # {'00': ~512, '11': ~512}

# Exact simulation with sf.simulate()
state = sf.simulate(qc, device="cpu")
print(state.numpy())       # [0.707+0j, 0, 0, 0.707+0j]
print(state.entropy())     # 0.0 (pure state)
print(state.purity())      # 1.0

# Expectation value (Rust-native)
zz_obs = [([3, 3], 1.0, 0.0)]  # ZZ observable
print(state.expectation(zz_obs))  # 1.0

# Parameterized circuit with gradient
qc = sf.Circuit(1).ry(sf.param("theta"), 0)
bound = qc.bind({"theta": 0.5})
state = sf.simulate(bound, device="cpu")
grads = state.grad([([3], 1.0, 0.0)], qc.to_ir(), {"theta": 0.5})
print(grads)  # {"theta": -0.479...}

Architecture

Python is the API, Rust Does the Work. All performance-critical computation runs in Rust. Python provides the fluent API surface. JAX is used only in nn/quantum_layer.py for the Flax custom_vjp bridge.

Python API (superfermion/)
    |-- Circuit, run(), simulate(), State, MethodError, RunResult
    |-- devices/      RustDevice (CPU/GPU), IBM, IonQ, Braket providers
    |-- observables/   PauliString, SparsePauliOp, Hamiltonian, expval
    |-- qml/          gradients (adjoint, param-shift, SPSA, QNG, Riemannian, SR)
    |-- nn/           Thin ML bridges: Flax/PyTorch/TF → sf.State.grad()
    |-- algorithms/   VQE, QAOA, QSVM, QBM, QRL + Grover, QPE, HHL
    |-- chemistry/    JW/BK transforms, UCCSD ansatz, PySCF bridge
    |-- qec/          codes + 4 decoders
    |-- compiler/     gate decomposition, rotation merge, SABRE routing
    |-- bridge/       Qiskit, Cirq, PennyLane, QASM interop
    |-- noise/        NoiseModel (Kraus channels for density matrix)
    |
    +-- _sf_core  (Rust PyO3 extension: State, QuantumDAG, ...)

Rust workspace (crates/)
    |-- sf-ir/        QuantumStateImpl trait, DAG, statevector, MPS,
    |                 stabilizer, density matrix simulation engines
    |-- sf-compiler/  Pass manager, gate cancellation, rotation merge
    |-- sf-router/    SABRE routing, hardware topology
    |-- sf-qec/       Stabilizer codes, MWPM/UnionFind decoders
    |-- sf-gpu/       CUDA statevector simulation (cudarc, sm_75+)
    |-- sf-bindings/  PyO3 FFI — State, QuantumDAG, compile

Execution flow

sf.run(circuit, device="cpu", method="statevector", shots=N)
    │
    ▼
runner.py — resolve device, bind params, optional compile
    │
    ▼
RustDevice.execute(dag, method, shots)
    │
    ├── statevector    → dag.simulate()             [Rust, Rayon]
    ├── mps            → dag.simulate_mps()         [Rust, faer]
    ├── stabilizer     → dag.simulate_stabilizer()  [Rust, tableau]
    ├── density_matrix → dag.simulate_dm_noisy()    [Rust, Kraus]
    └── gpu            → dag.simulate_gpu()         [CUDA]
    │
    ▼
sf.State (Rust-native) → RunResult(counts, state, metadata)

Simulation Methods

# MPS simulation
result = sf.run(circuit, device="cpu", method="mps", shots=10000, bond_dim=64)

# Stabilizer simulation
result = sf.run(clifford_circuit, device="cpu", method="stabilizer", shots=10000)

# GPU simulation (requires CUDA)
result = sf.run(circuit, device="gpu", shots=0)

Benchmarks

Performance measured against Qiskit Aer 0.17 and PennyLane Lightning 0.45 on CPU (details in notebooks/). Speedups are regime-dependent; the caveats below are part of the claim.

Key Modules

Gradients

Machine Learning Layers

from superfermion.nn.quantum_layer import QuantumLayer     # Flax (JAX)
from superfermion.nn.torch_layer import TorchQuantumLayer  # PyTorch
from superfermion.nn.tf_layer import TFQuantumLayer        # TensorFlow

Quantum Error Correction

from superfermion.qec import SurfaceCode2D, MWPMDecoder, QECManager

code = SurfaceCode2D(distance=3)
circuit = code.build()

Cross-Framework Bridge

from superfermion.bridge import from_qiskit, to_qiskit, from_pennylane, to_cirq

sf_circuit = from_qiskit(qiskit_circuit)
qiskit_circuit = to_qiskit(sf_circuit)

Documentation

Full documentation is available at superfermion.com (or superfermion-docs.pages.dev).

Citing

@misc{superfermion-2026,
  title  = {SuperFermion: a high-performance quantum-circuit simulator
            with native adjoint differentiation},
  author = {SuperFermion Team},
  year   = {2026},
  url    = {https://github.com/Catstate101/superfermion}
}

License

Apache License 2.0.