Skip to main content

Release License Docs Qiskit Python rustc Platform Tests Coverage

Qiskit Fermions

qiskit-fermions extends the Qiskit SDK with tools for working on fermionic systems. Within its scope it provides the following:

  • Efficient data structures for the representation and manipulation of fermionic operators in different forms
  • A framework for implementing operator conversion methods (including fermion-to-qubit encodings)
  • A library of efficient implementations of common conversion methods
  • A framework and library of gates for expressing fermionic circuits
  • A transpilation pipeline integrated with the Qiskit transpiler process to synthesize fermionic circuits into qubit-based circuits

Additionally, qiskit-fermions integrates with other tools of the ecosystem, such as:


Documentation

Documentation for this package is available on IBM Quantum Platform.

You can also preview the docs of the development branch on Github pages.


Installation

C

Refer to the C installation instructions.

Python

Install this package via pip, when possible:

pip install 'qiskit-fermions'

For more installation information, refer to these installation instructions.


Get started

Overview

The schematic description in the image above provides a glimpse of the breadth of features and general workflow that this package provides. You can work in the fermionic regime with both, operator and circuit representation, before you define a fermion-to-qubit encoding that plugs into the multi-representation transpiler pipeline of Qiskit.

All of these features are explained in several guides to help you get started. For an overview working through exactly the pipeline shown above, start with the 1D Fermi-Hubbard guide.


Use case examples

Components of this package have been used in research related to the following papers:

  • The qDRIFT randomized circuit compilation in 1.
  • The fermion-to-qubit synthesis during the transpilation process in 2.

Technical discussion

Design intentions

This package is deliberately designed to align with Qiskit: it builds on a core implemented in Rust and provides first-party language bindings to Python and C. Its API intends to draw parallels to Qiskit in order to seamlessly integrate into the workflows of users with experience in programming Qiskit.

A core principle to the design of qiskit-fermions was the decoupling of its fermionic circuit representation from its qubitized form. To be more precise: the fermionic circuits are meaningful by themselves and do not require a mapping to qubit space to be interpretable. Furthermore, the fermionic circuit representation cannot make any assumptions about its fermion-to-qubit encoding applied later on. Consequently, while Jordan-Wigner retains a dominant position and role, it is not assumed to be the default fermion-to-qubit encoding.

Relationship to ffsim

ffsim and qiskit-fermions divide the work rather than overlap. ffsim owns the high-level ansatz operators and their fast simulation: it constructs a UCJ or UCCSD operator from coupled-cluster amplitudes or a parameter vector, and simulates fermionic states in a compact fixed-particle-number space. qiskit-fermions owns the circuit side: it expresses that operator as a fermionic circuit on fermionic modes and transpiles it into a qubit circuit through any fermion-to-qubit encoding.

That last point is the reason to bring an ffsim operator here. ffsim's own Qiskit gates are specific to the Jordan-Wigner transformation, so lowering an ansatz through a different encoding (a local encoding trading qubits for shallower circuits, for instance) is what this package adds. Conversely, this package does not reimplement the ansatz math, so its UCJ and UCC gates take an ffsim operator directly as their input.

On the simulation side, ffsim is the backend. This package's gates and operators implement the protocol methods ffsim's simulation functions consume (_apply_unitary_, _linear_operator_ and _trace_), so ffsim's tools work on them natively, with no conversion step. Because ffsim depends on PySCF, which does not support Windows, simulating on Windows means going through WSL for now. Building operators, mapping them and transpiling the resulting circuits need none of this and work everywhere.

For the full picture, refer to the ffsim relationship guide.

Known issues

As long as the Qiskit C API has not yet reached feature parity with its Python API, some components of this package remain exclusive to its Python API, too. This includes the entire circuit library (qiskit_fermions.circuit) as well as transpiler passes (qiskit_fermions.transpiler).

Future work

  • Migrate the circuit library and transpiler passes into the Rust core (and provide a C API for interacting with them)
  • Extend the library of efficient operator conversion implementations
  • Extend the library of efficient operator data structures

Contributing

The source code is available on GitHub.

The developer guide is located at CONTRIBUTING.md in the root of this project's repository. By participating, you are expected to uphold Qiskit's code of conduct.


Citing this package

If you use this package in your research, use the CITATION.bib file in this project’s repository to cite the appropriate reference(s).


License

Apache License 2.0


Deprecation policy

This package follows semantic versioning. Breaking changes are made only occasionally, to improve the user experience. When possible, old interfaces are kept and marked as deprecated for as long as they can co-exist with the new ones. Each substantial improvement, breaking change, or deprecation is documented in the release notes.


References

  1. Samuele Piccinelli, et al., Quantum chemistry with provable convergence via randomized sample-based Krylov quantum diagonalization, arXiv:2508.02578 [quant-ph]. ↩

  2. Anthony Gandon, et al., Stabilizer-based quantum simulation of fermion dynamics with local qubit encodings, arXiv:2512.11418 [quant-ph]. ↩

Metadata

Release files for qiskit-fermions 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for qiskit-fermions 0.3.0
File Size Uploaded Provenance Actions
qiskit_fermions-0.3.0.tar.gz 178.2 kB With provenance Details for qiskit_fermions-0.3.0.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for qiskit-fermions 0.3.0
File Actions
qiskit_fermions-0.3.0-cp311-abi3-win_amd64.whl CPython 3.11 abi3 Windows x86-64 Details for qiskit_fermions-0.3.0-cp311-abi3-win_amd64.whl
qiskit_fermions-0.3.0-cp311-abi3-manylinux_2_28_x86_64.whl CPython 3.11 abi3 Linux glibc 2.28+ x86-64 Details for qiskit_fermions-0.3.0-cp311-abi3-manylinux_2_28_x86_64.whl
qiskit_fermions-0.3.0-cp311-abi3-manylinux_2_28_aarch64.whl CPython 3.11 abi3 Linux glibc 2.28+ ARM64 Details for qiskit_fermions-0.3.0-cp311-abi3-manylinux_2_28_aarch64.whl
qiskit_fermions-0.3.0-cp311-abi3-macosx_11_0_arm64.whl CPython 3.11 abi3 macOS 11.0+ ARM64 Details for qiskit_fermions-0.3.0-cp311-abi3-macosx_11_0_arm64.whl
qiskit_fermions-0.3.0-cp311-abi3-macosx_10_12_x86_64.whl CPython 3.11 abi3 macOS 10.12+ x86-64 Details for qiskit_fermions-0.3.0-cp311-abi3-macosx_10_12_x86_64.whl

Total release size: 9.0 MB

Release files / qiskit_fermions-0.3.0.tar.gz

Download URL qiskit_fermions-0.3.0.tar.gz
Size 178.2 kB
Tags Source
SHA-256 checksum
How to use checksums
457681bbe782ad812bd03711dd3e0d7977a1daef0dadea138ca5ce442f0009de
BLAKE2b-256 checksum
How to use checksums
e72035d2dc9f809cf6b7f690e55382b4048404ab145d4dc1526c68bb8edcd059
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 22, 2026.

Transparency log

Release files / qiskit_fermions-0.3.0-cp311-abi3-win_amd64.whl

Download URL qiskit_fermions-0.3.0-cp311-abi3-win_amd64.whl
Size 1.6 MB
Tags CPython 3.11 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
1b4df9b555416be2dbf994b4589ef74a7c6a3b4b84b436e66a3dcca023cf79a0
BLAKE2b-256 checksum
How to use checksums
1f388efc8d601aa8716a46ef4e371787c42f99ca19df666928425ea1190c8bc7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 22, 2026.

Transparency log

Release files / qiskit_fermions-0.3.0-cp311-abi3-manylinux_2_28_x86_64.whl

Download URL qiskit_fermions-0.3.0-cp311-abi3-manylinux_2_28_x86_64.whl
Size 1.9 MB
Tags CPython 3.11 Linux glibc 2.28+ x86-64 abi3
SHA-256 checksum
How to use checksums
061b4266d0533007c4424a9dd4286fdf52d215c15dacd0ed2456822cece3a343
BLAKE2b-256 checksum
How to use checksums
c9532feed6707e2c13651b9c76f75c169d75162c647a44257e0b79df69062f55
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 22, 2026.

Transparency log

Release files / qiskit_fermions-0.3.0-cp311-abi3-manylinux_2_28_aarch64.whl

Download URL qiskit_fermions-0.3.0-cp311-abi3-manylinux_2_28_aarch64.whl
Size 1.9 MB
Tags CPython 3.11 Linux glibc 2.28+ ARM64 abi3
SHA-256 checksum
How to use checksums
3edcd5524d19bf8b1ac938d91ffcf9425c919753e2f054b1cbca1c3584441ede
BLAKE2b-256 checksum
How to use checksums
564dd5ba590950b63aa940430a673ab19be6d7f8971855e0cdd70eb615718cdf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 22, 2026.

Transparency log

Release files / qiskit_fermions-0.3.0-cp311-abi3-macosx_11_0_arm64.whl

Download URL qiskit_fermions-0.3.0-cp311-abi3-macosx_11_0_arm64.whl
Size 1.7 MB
Tags CPython 3.11 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
ef0cd8d7a3b65cc1bd804434507cba0629ecc439798fd1fa89f7bf8d4c1c9e75
BLAKE2b-256 checksum
How to use checksums
b20cc214ff1904832a595804987e9dbcce2726ddec67b19cd7bfffd3a467e3b6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 22, 2026.

Transparency log

Release files / qiskit_fermions-0.3.0-cp311-abi3-macosx_10_12_x86_64.whl

Download URL qiskit_fermions-0.3.0-cp311-abi3-macosx_10_12_x86_64.whl
Size 1.8 MB
Tags CPython 3.11 abi3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
3b9971e3614ed84731a72fc31c5d0b96eb5f1ef1e55277b56a164d6a1b1a5b20
BLAKE2b-256 checksum
How to use checksums
c262112006efedc37dade50f5011ec923a62f98bbc5cf796e6552bf081da3b06
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 22, 2026.

Transparency log

Security for qiskit-fermions 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 6 files in this release have been uploaded with provenance metadata.

Select from 6 files

Attestation for qiskit_fermions-0.3.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 22, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page