Skip to main content

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.

Python 3.10+ Rust 1.75+ License: Apache 2.0


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; up to 200x faster than parameter-shift for 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 — 10 codes (Repetition, Shor, Steane, Bacon-Shor, Surface, Toric, Color, Honeycomb, Hypercube, CSS) + 4 decoders (MWPM, Union-Find, BP+OSD, Neural)
  • Multi-framework MLQuantumLayer (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

git clone https://github.com/Catstate101/superfermion.git
cd superfermion
pip install -e .

# Build the Rust extension (required for simulation)
pip install maturin
cd crates/sf-bindings && maturin develop --release && cd ../..

# Copy the built extension into the package
# Linux:
cp target/release/lib_sf_core.so superfermion/_sf_core.so
# macOS:
# cp target/release/lib_sf_core.dylib superfermion/_sf_core.so
# Windows:
# cp target/release/_sf_core.dll superfermion/_sf_core.pyd

Requirements: Python 3.10–3.13, Rust 1.75+, ~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/          10 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

Method Max Qubits Best For
statevector (default) ~25 CPU, ~30 GPU Exact simulation, gradient computation
mps 200+ Low-entanglement circuits (QAOA, VQE, GHZ)
stabilizer ~1000 Clifford-only circuits (QEC, randomized benchmarking)
density_matrix ~12 Noisy simulation with Kraus channels
# 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/).

Workload SF vs Competitor Speedup
Stabilizer (n=10–500, 10k shots) vs Qiskit Aer stabilizer 3.7–6.8x
MPS GHZ (n=10–100, 10k shots) vs Qiskit Aer MPS 21–33x
Adjoint gradient (n=4–16, depth=1) vs PennyLane Lightning 1.5–800x
Adjoint vs param-shift (n=10) SF internal 20–198x (grows with params)
Shot sampling (n=10–22, 100k shots) vs Qiskit Aer 1.6–9.5x
VQE H2 end-to-end vs PennyLane Lightning 100x

Key Modules

Gradients

Method File Description
Adjoint qml/gradient/adjoint.py 1 forward + 1 backward pass; fastest for most QML
Parameter-shift qml/gradient/parameter_shift.py 2 forward passes per param; analytic
Finite difference qml/gradient/parameter_shift.py Centered difference fallback
SPSA qml/gradient/spsa.py Stochastic approximation; noisy-hardware friendly
Quantum Natural qml/gradient/qng.py Fubini-Study metric; faster convergence

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).

Document Content
docs/usage_guide.md Canonical API reference with runnable examples
docs/architecture.md Hexagonal architecture, module map, execution flow
CONTRIBUTING.md Contribution guide
CHANGELOG.md Release history

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.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

superfermion-0.1.5.tar.gz (283.5 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

superfermion-0.1.5-cp313-cp313-win_amd64.whl (1.3 MB view details)

Uploaded CPython 3.13Windows x86-64

superfermion-0.1.5-cp313-cp313-manylinux_2_28_x86_64.whl (1.5 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.28+ x86-64

superfermion-0.1.5-cp313-cp313-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl (2.5 MB view details)

Uploaded CPython 3.13macOS 10.12+ universal2 (ARM64, x86-64)macOS 10.12+ x86-64macOS 11.0+ ARM64

superfermion-0.1.5-cp312-cp312-win_amd64.whl (1.3 MB view details)

Uploaded CPython 3.12Windows x86-64

superfermion-0.1.5-cp312-cp312-manylinux_2_28_x86_64.whl (1.5 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.28+ x86-64

superfermion-0.1.5-cp312-cp312-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl (2.5 MB view details)

Uploaded CPython 3.12macOS 10.12+ universal2 (ARM64, x86-64)macOS 10.12+ x86-64macOS 11.0+ ARM64

superfermion-0.1.5-cp311-cp311-win_amd64.whl (1.3 MB view details)

Uploaded CPython 3.11Windows x86-64

superfermion-0.1.5-cp311-cp311-manylinux_2_28_x86_64.whl (1.5 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.28+ x86-64

superfermion-0.1.5-cp311-cp311-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl (2.5 MB view details)

Uploaded CPython 3.11macOS 10.12+ universal2 (ARM64, x86-64)macOS 10.12+ x86-64macOS 11.0+ ARM64

superfermion-0.1.5-cp310-cp310-win_amd64.whl (1.3 MB view details)

Uploaded CPython 3.10Windows x86-64

superfermion-0.1.5-cp310-cp310-manylinux_2_28_x86_64.whl (1.5 MB view details)

Uploaded CPython 3.10manylinux: glibc 2.28+ x86-64

superfermion-0.1.5-cp310-cp310-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl (2.5 MB view details)

Uploaded CPython 3.10macOS 10.12+ universal2 (ARM64, x86-64)macOS 10.12+ x86-64macOS 11.0+ ARM64

File details

Details for the file superfermion-0.1.5.tar.gz.

File metadata

  • Download URL: superfermion-0.1.5.tar.gz
  • Upload date:
  • Size: 283.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for superfermion-0.1.5.tar.gz
Algorithm Hash digest
SHA256 31c47b702e470c42f06ecc2febba7b1876bdb6670861f80a55e238855f09d321
MD5 834bb76357693352dacac74247bdf429
BLAKE2b-256 4481af832f722fc12d90ebcefe0786b792e559bef3cd451a8f1b79d8d63cf78b

See more details on using hashes here.

Provenance

The following attestation bundles were made for superfermion-0.1.5.tar.gz:

Publisher: release.yml on Catstate101/superfermion

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file superfermion-0.1.5-cp313-cp313-win_amd64.whl.

File metadata

File hashes

Hashes for superfermion-0.1.5-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 5bc77f9dd3ee28f2dce0304327e15eb5ca53ae0487df596c06ebd460735657b4
MD5 17c1434d7a73ec1532633075834d863a
BLAKE2b-256 59f9d3614cdacdd48a79ea85a347a8a2d883154aefbb2e7a8b22a8b9c1ac0cb3

See more details on using hashes here.

Provenance

The following attestation bundles were made for superfermion-0.1.5-cp313-cp313-win_amd64.whl:

Publisher: release.yml on Catstate101/superfermion

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file superfermion-0.1.5-cp313-cp313-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for superfermion-0.1.5-cp313-cp313-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 3c347c6300d13ab4a0ff973ae03fdf552ac0f0fd91285b6f9a00cad7b8d9a1f9
MD5 a5afb4cbbf85203b3871031db3da357d
BLAKE2b-256 dd6998cd2b95a8bec3c3d69714b0c95e51eea77ba10dad23c4f11250efd0e908

See more details on using hashes here.

Provenance

The following attestation bundles were made for superfermion-0.1.5-cp313-cp313-manylinux_2_28_x86_64.whl:

Publisher: release.yml on Catstate101/superfermion

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file superfermion-0.1.5-cp313-cp313-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl.

File metadata

File hashes

Hashes for superfermion-0.1.5-cp313-cp313-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl
Algorithm Hash digest
SHA256 0ef1eff8fae0bbcf61e8e15d90765f521fcd687af338f25ace2f9af36d9a26eb
MD5 134b39d61292ae3b20e74c19eaa57a8e
BLAKE2b-256 cc6c8c11c0ea743016d45e578b575df87bfe96dd3c604533e1f3411b7911c3e6

See more details on using hashes here.

Provenance

The following attestation bundles were made for superfermion-0.1.5-cp313-cp313-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl:

Publisher: release.yml on Catstate101/superfermion

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file superfermion-0.1.5-cp312-cp312-win_amd64.whl.

File metadata

File hashes

Hashes for superfermion-0.1.5-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 09ac1a2f773f3b347083a99a6e93e03aaba261eaf5a18090d4be4d22c07dd5f4
MD5 d19d73af7c08c956382d68e384aa876d
BLAKE2b-256 d80bd89435b1045a98158a9d3ff1fdb758cce8100fbbc960382918a8818932d5

See more details on using hashes here.

Provenance

The following attestation bundles were made for superfermion-0.1.5-cp312-cp312-win_amd64.whl:

Publisher: release.yml on Catstate101/superfermion

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file superfermion-0.1.5-cp312-cp312-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for superfermion-0.1.5-cp312-cp312-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 933030eab2283d5a72b87fb1773139cab5347959e7cbfb3b9848a4b9ee8411f7
MD5 e07254c0a8c9da1b93d8f44eb1599c98
BLAKE2b-256 8fec8d361c892d1cb9bc80149ca5512e65fa306f2847211d9bc81f6f7855e126

See more details on using hashes here.

Provenance

The following attestation bundles were made for superfermion-0.1.5-cp312-cp312-manylinux_2_28_x86_64.whl:

Publisher: release.yml on Catstate101/superfermion

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file superfermion-0.1.5-cp312-cp312-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl.

File metadata

File hashes

Hashes for superfermion-0.1.5-cp312-cp312-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl
Algorithm Hash digest
SHA256 5cce8ca01c4085126207ceec929394eec46a19f8580ed9bc08ca9e73b6bddc3b
MD5 ffb78755b9bba4cdbb68837b3256c879
BLAKE2b-256 8662f6fa95756e186c68806f6f1d5d70dc21a0cac21033e43db29ec8399a87cc

See more details on using hashes here.

Provenance

The following attestation bundles were made for superfermion-0.1.5-cp312-cp312-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl:

Publisher: release.yml on Catstate101/superfermion

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file superfermion-0.1.5-cp311-cp311-win_amd64.whl.

File metadata

File hashes

Hashes for superfermion-0.1.5-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 8c45a1d742a6b785d3d9e0c93abb27427c264d9ed204422c5a6d8914623b921b
MD5 db42fd9dcf6ed8748530e33694842b4d
BLAKE2b-256 93c97d6dec61017758a13e36a17e9a30574218e9a893d8ee7d68cd4ac991c450

See more details on using hashes here.

Provenance

The following attestation bundles were made for superfermion-0.1.5-cp311-cp311-win_amd64.whl:

Publisher: release.yml on Catstate101/superfermion

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file superfermion-0.1.5-cp311-cp311-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for superfermion-0.1.5-cp311-cp311-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 8c14282654910d917355760f5a42d3144990e144b2c2aa5498754032717918f1
MD5 e6d36e44e786a325785d3cd174983626
BLAKE2b-256 4837f77d8ba3eb2ef8bbb08a6e2b61dbec62e98fd9edbd90443f39aea6dd3a55

See more details on using hashes here.

Provenance

The following attestation bundles were made for superfermion-0.1.5-cp311-cp311-manylinux_2_28_x86_64.whl:

Publisher: release.yml on Catstate101/superfermion

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file superfermion-0.1.5-cp311-cp311-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl.

File metadata

File hashes

Hashes for superfermion-0.1.5-cp311-cp311-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl
Algorithm Hash digest
SHA256 c0426925e589c44838cc211bd16da347d4c99b5d37d06238a3c2fa9f3438ecea
MD5 c48c4caa4fd8e6552ce6a00d506f2769
BLAKE2b-256 45e44b18b17f0492440525c8385ad75f26191eba986553e4c3268f7372587c18

See more details on using hashes here.

Provenance

The following attestation bundles were made for superfermion-0.1.5-cp311-cp311-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl:

Publisher: release.yml on Catstate101/superfermion

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file superfermion-0.1.5-cp310-cp310-win_amd64.whl.

File metadata

File hashes

Hashes for superfermion-0.1.5-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 362f8e598c14cd047605f6f8012b0d282fdba805963c460595dfb9d548640154
MD5 c40d5580ba07b80c863399aad030779a
BLAKE2b-256 eb5d30ea9012f4b572dc8628b9a59694fe65a78dd818291cfdd796fb08565809

See more details on using hashes here.

Provenance

The following attestation bundles were made for superfermion-0.1.5-cp310-cp310-win_amd64.whl:

Publisher: release.yml on Catstate101/superfermion

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file superfermion-0.1.5-cp310-cp310-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for superfermion-0.1.5-cp310-cp310-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 d0b18a10a61a14247b8645b28cf17d6390b68220f83aa5ac9ea96fba45a50666
MD5 d99ce9909b1d384a4d760185cfee6483
BLAKE2b-256 6c020f629ac7e07842f6b62649f551fa1c59472006bc9e57746a1f396b7c2dbf

See more details on using hashes here.

Provenance

The following attestation bundles were made for superfermion-0.1.5-cp310-cp310-manylinux_2_28_x86_64.whl:

Publisher: release.yml on Catstate101/superfermion

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file superfermion-0.1.5-cp310-cp310-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl.

File metadata

File hashes

Hashes for superfermion-0.1.5-cp310-cp310-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl
Algorithm Hash digest
SHA256 bf0c7abfe5eb71fe45cca8c61d887d8614fe00859b0ef62923178d2cbd2f5c2b
MD5 b70cf39a9b1e5b90c06392e4712b937a
BLAKE2b-256 fb4e3f8c683610406a3a200cde762b9c3969c1a1a2eb531b438bd54d899fab5c

See more details on using hashes here.

Provenance

The following attestation bundles were made for superfermion-0.1.5-cp310-cp310-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl:

Publisher: release.yml on Catstate101/superfermion

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page