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.3.tar.gz (283.4 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.3-cp313-cp313-win_amd64.whl (1.3 MB view details)

Uploaded CPython 3.13Windows x86-64

superfermion-0.1.3-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.3-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.3-cp312-cp312-win_amd64.whl (1.3 MB view details)

Uploaded CPython 3.12Windows x86-64

superfermion-0.1.3-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.3-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.3-cp311-cp311-win_amd64.whl (1.3 MB view details)

Uploaded CPython 3.11Windows x86-64

superfermion-0.1.3-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.3-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.3-cp310-cp310-win_amd64.whl (1.3 MB view details)

Uploaded CPython 3.10Windows x86-64

superfermion-0.1.3-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.3-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.3.tar.gz.

File metadata

  • Download URL: superfermion-0.1.3.tar.gz
  • Upload date:
  • Size: 283.4 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.3.tar.gz
Algorithm Hash digest
SHA256 3021bbc7f11c29183c120412e353ca5ba325b0f32c8150becc6c7499dce351d3
MD5 f96e5ca1215995f1ab840a8fcf1ce28a
BLAKE2b-256 e032675e26df658bbe3ac8927c2806f7e75bc9ec7a62a06d9b6552060859db8a

See more details on using hashes here.

Provenance

The following attestation bundles were made for superfermion-0.1.3.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.3-cp313-cp313-win_amd64.whl.

File metadata

File hashes

Hashes for superfermion-0.1.3-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 c8ee5624fca12864e871f41ee7410c71ecbe399ebc54505625c8bd80f0a138fc
MD5 b6baf735968988ceb0441254764a76fc
BLAKE2b-256 85363a1f98608e6bdce7b7e140834bb761817cf60781feb6eb8ce4b01ffd9d76

See more details on using hashes here.

Provenance

The following attestation bundles were made for superfermion-0.1.3-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.3-cp313-cp313-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for superfermion-0.1.3-cp313-cp313-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 68b3751d3425b04235462b1e6e492ce592c78ef620ff2be2e952f325d6c2637f
MD5 394b282009a36a26480ad83313ca1eed
BLAKE2b-256 788ae1d92473496634de5e64ba67ffd4e2c129f2e5cf61844c574112fa86d2d3

See more details on using hashes here.

Provenance

The following attestation bundles were made for superfermion-0.1.3-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.3-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.3-cp313-cp313-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl
Algorithm Hash digest
SHA256 6e0f459f4c7048d54e3e9b6673d42a3b23392651c8c57601785a4e5e07662597
MD5 556e9013738fab46bea51c24353b3c5e
BLAKE2b-256 be40454e0a43e3d2c74eabdf9f169eb850e6bb8e09f7036604382076b7f7833c

See more details on using hashes here.

Provenance

The following attestation bundles were made for superfermion-0.1.3-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.3-cp312-cp312-win_amd64.whl.

File metadata

File hashes

Hashes for superfermion-0.1.3-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 88effb74590f974451abe7be9f400e6d516a313387ee17f33376f520193deec6
MD5 e1b0961f704eb398cd3bef818a777dc1
BLAKE2b-256 b940289c556228ea8fd7d135420218814b8afa0190dc4eb20ef1c212b2734324

See more details on using hashes here.

Provenance

The following attestation bundles were made for superfermion-0.1.3-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.3-cp312-cp312-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for superfermion-0.1.3-cp312-cp312-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 74801a0f86998a5253795e9a48a73b56810867ce82d423ae5ac237abe430f149
MD5 ffeb293e5a3a13a0e8ea1020f92de0c7
BLAKE2b-256 27fd0d051496f70ec0fe3e0adbab25e087e0386ee3632f203dbe64de0231a169

See more details on using hashes here.

Provenance

The following attestation bundles were made for superfermion-0.1.3-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.3-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.3-cp312-cp312-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl
Algorithm Hash digest
SHA256 99a908c782bd01fdb33aebff307247e678246ca6c0ee054d0ee78cd08f68f569
MD5 6665b491934d876cb4c2ac80c5f6d4b8
BLAKE2b-256 b5b1d6cb149ed4e2434c92540f4580d79d16309a8c56a9dfaf65274ffb2e5fbf

See more details on using hashes here.

Provenance

The following attestation bundles were made for superfermion-0.1.3-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.3-cp311-cp311-win_amd64.whl.

File metadata

File hashes

Hashes for superfermion-0.1.3-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 ab8ab8534a77632d4e65fdf8ab25a1815af1f2197fca340d31214c76b557d2f0
MD5 846f4dd2b98b6151fe1de6262971efa3
BLAKE2b-256 01211acc086fbc458c83df4de7c481640b2b94e83bb09e88ab9005bca812e6ef

See more details on using hashes here.

Provenance

The following attestation bundles were made for superfermion-0.1.3-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.3-cp311-cp311-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for superfermion-0.1.3-cp311-cp311-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 91787e367c8913360e1b3a78a51a9d24508632c9a45eaa44178710a22d849124
MD5 8295fea6a8c74af1d215e3667a23694d
BLAKE2b-256 682e9d4b61b6ea238310f35d02ad35be6fea4926c64b9febe2bda5801c4e121e

See more details on using hashes here.

Provenance

The following attestation bundles were made for superfermion-0.1.3-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.3-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.3-cp311-cp311-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl
Algorithm Hash digest
SHA256 efc6c651463ce27ae01e859c96dad08813f9861de897d4ccc3a3b0f6a7f6a2a0
MD5 85b1684b3318f29fd1f42c9dad269d0e
BLAKE2b-256 257791bd044f05edd68fd0f6b140fa2dcbad9913f08e7d8817205846e9aff92a

See more details on using hashes here.

Provenance

The following attestation bundles were made for superfermion-0.1.3-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.3-cp310-cp310-win_amd64.whl.

File metadata

File hashes

Hashes for superfermion-0.1.3-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 54c55f59d88152f49f448b5e8e256fb00d1f31f74c987ec7a1fe03b4aec193df
MD5 569f4f3d5da7d584090528914ddf5716
BLAKE2b-256 890e01f331031f507b046cb932386b50fca24d0231c6331423f27887946eef90

See more details on using hashes here.

Provenance

The following attestation bundles were made for superfermion-0.1.3-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.3-cp310-cp310-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for superfermion-0.1.3-cp310-cp310-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 bdf81ff6abed5b81d3898c3f6ae7d8e5ddab9ef8947747fa3bbfc9505606e9ce
MD5 bebbc44f93e06712aa77fc8cc853140c
BLAKE2b-256 d983aabd8882a375d68d2cb01ef48abd707952a7fd9118ecc466286f73821d70

See more details on using hashes here.

Provenance

The following attestation bundles were made for superfermion-0.1.3-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.3-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.3-cp310-cp310-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl
Algorithm Hash digest
SHA256 56fe8473aed7297445a81ab5fdaffc18b973527585a8db340434faa193416cfd
MD5 a17a6d590d465f594dd8056bb5a7ed70
BLAKE2b-256 237315852aac9ffa7cfabfb8d9fc5ae710cc49ac211072a0fae097a1bed64403

See more details on using hashes here.

Provenance

The following attestation bundles were made for superfermion-0.1.3-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