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.4.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.4-cp313-cp313-win_amd64.whl (1.3 MB view details)

Uploaded CPython 3.13Windows x86-64

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

Uploaded CPython 3.12Windows x86-64

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

Uploaded CPython 3.11Windows x86-64

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

Uploaded CPython 3.10Windows x86-64

superfermion-0.1.4-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.4-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.4.tar.gz.

File metadata

  • Download URL: superfermion-0.1.4.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.4.tar.gz
Algorithm Hash digest
SHA256 31f1dfa5469c99e5b5293fcb73aa6feb7d139d25dc0d0e2042344488791f2422
MD5 02c4c50b87d902e6259aa30f97135413
BLAKE2b-256 18ddf01a830ae462aefb0983434dc1517237c9219f214e9b2c44f9987f9f437b

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for superfermion-0.1.4-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 9b5a3814be4ffd34e97cabf66b736fd5ded37588a8d9002e43b1f0d3a6b10640
MD5 217135809c6f2e968d93a1c81212ea0d
BLAKE2b-256 4c49a28e1efd211fdaf12c04c1309eebe146ff5f1323f101f995d9f9651c5070

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for superfermion-0.1.4-cp313-cp313-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 e771bda9ca908db998350707e81eab595e511d26d95dad3bcff639be55ef1e27
MD5 90ef41a493753e54db293d2cd2ad9cd9
BLAKE2b-256 cca44b01bb1beafcd13192ebfcd9be2cf6dac9f0b532d251850545e5664cefcd

See more details on using hashes here.

Provenance

The following attestation bundles were made for superfermion-0.1.4-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.4-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.4-cp313-cp313-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl
Algorithm Hash digest
SHA256 90da2274183df958fbf86495ee9cc112d59ea391cb65c85deb544c305fe5e1c8
MD5 4fb23fc2d0f0683ad7348b892eee9cbc
BLAKE2b-256 4cf26bae278ee54a4b1951492d5a8be56a0dec67274461426a900b1dc4a22ecd

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for superfermion-0.1.4-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 cc64c1ec1bcde2d089265e3cc9eda0fadf6ee6351330acb725512a819daa5961
MD5 81e8867d2ea4076cec97b313613db82e
BLAKE2b-256 686ad0716e8650321aee8187780835b5b6af8bbdff74502123d26ac9b4bbe791

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for superfermion-0.1.4-cp312-cp312-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 7802bb8fa436ef27a056b02f10d717b542d42822a69c146b41e2afc2e2322bfc
MD5 9b55d77a1c0027ac8b5397282d57c6c9
BLAKE2b-256 8c25132aaf713b17ecf56109548cb9d6e519f79d6b1041a3b43b6babd414b230

See more details on using hashes here.

Provenance

The following attestation bundles were made for superfermion-0.1.4-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.4-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.4-cp312-cp312-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl
Algorithm Hash digest
SHA256 e48f1c15dae5e6813dd8b3af7a8b3dccd779d6c7ed602b647a20b62684803767
MD5 8428e63770f5e1bf37f460116a9ee955
BLAKE2b-256 08761f8dd3c8a81c0adc7349246d3018bfa264449171139acd6b34ff13f2ed87

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for superfermion-0.1.4-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 f7f148a15e13c4ca0fa6714583f58b3de954b27e4be6bccbd3005f54f2e7f65a
MD5 83e369b219a67480dd641fe1a721a39d
BLAKE2b-256 7689b621bf9902c05479223d2c885d2c37e0544d1c07ffcadbd51b8b362703f9

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for superfermion-0.1.4-cp311-cp311-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 b7bda59f6bd6ca01466d29d3cf7172a6d2d851f899c019cdd38715f9db15c842
MD5 50adf8cfdd548da4b27daba54dc8ffc4
BLAKE2b-256 46006ccd8bcc7e7974917aa02fdeefb4a6cb2e9f77f6ce335f689bd36879e391

See more details on using hashes here.

Provenance

The following attestation bundles were made for superfermion-0.1.4-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.4-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.4-cp311-cp311-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl
Algorithm Hash digest
SHA256 2e1eee8c59493d4ac2b4d99508264c6d9459646220a85f98eba3d075ab5e1d38
MD5 0af7d48e39a205492ed3d9a846fe832b
BLAKE2b-256 682198679a92c66c1ba891bf702e6de298caf627d5f1a34a7d8ee1bb41573d85

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for superfermion-0.1.4-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 ac8830e1390e5340ba6234bd52e0c9fe5b2dd0acccaafd533cde0c567ae4365c
MD5 a218623085b6f8f6d8a017be6622e2f0
BLAKE2b-256 c19c41bbc480ec8cdadef8a69c6604fec26ce062995fd9c71d4048f39bd206cd

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for superfermion-0.1.4-cp310-cp310-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 e6dd088902642035d786724ab4a3cd95e9e4509989453d5f5e9cef5b395ff10b
MD5 9146fed9366c26604818766b604695e1
BLAKE2b-256 8ca03e210658d43da6f42f3f13aba50683ccbf20999592a20eeb416a1f9a9d1c

See more details on using hashes here.

Provenance

The following attestation bundles were made for superfermion-0.1.4-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.4-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.4-cp310-cp310-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl
Algorithm Hash digest
SHA256 04bd1a0359643c11c0eb41da6a40703da7d59249bb45e587c0204b0d685b4dd7
MD5 ec14f037df133abd727b4f17033b66be
BLAKE2b-256 c44fbf1978f63259d80d063ab7e53c7d647accbd8c017d23ee69fa6120c9206d

See more details on using hashes here.

Provenance

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