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.4.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.4.0
File Size Uploaded Provenance Actions
qiskit_fermions-0.4.0.tar.gz 192.3 kB With provenance Details for qiskit_fermions-0.4.0.tar.gz

Built distributions (wheels)

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

Total release size: 9.1 MB

Release files / qiskit_fermions-0.4.0.tar.gz

Download URL qiskit_fermions-0.4.0.tar.gz
Size 192.3 kB
Tags Source
SHA-256 checksum
How to use checksums
de303b945b80035705dd1bdc8689e4323c4fa8a05ac5b734c78986ad193f8f4a
BLAKE2b-256 checksum
How to use checksums
3d6146310d01dda7a0acd309ae5e696f8f97f632902e9e63c70b9029fe49602a
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 Nov 4, 2026.

Transparency log

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

Download URL qiskit_fermions-0.4.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
b8d93ada66b0f9ada1ec13789b8fb3b7c0d8a6b1d0a942450bac66a9f6ce24b7
BLAKE2b-256 checksum
How to use checksums
2c109c4b47d37feeca529994a8968337d6c532924f4939f241646a5b396dfdbc
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 Nov 4, 2026.

Transparency log

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

Download URL qiskit_fermions-0.4.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
692a690028209cb88968e94ad6ca6577ee5d085483977f42fb3355bd6f285ad5
BLAKE2b-256 checksum
How to use checksums
cd7d492ac9dc51600dfbb2556d667eb82987ea5d648e5f76f12bfd28b279e6b0
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 Nov 4, 2026.

Transparency log

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

Download URL qiskit_fermions-0.4.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
9d4f7e3f677335fbac0af8efcf54c7aa5fd51c4c715ef38d5e879dc2eb3991d6
BLAKE2b-256 checksum
How to use checksums
b69fc6d3d963fb8b040ba7afb780c727e0ae65b6fa60065eb26508d79e20e527
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 Nov 4, 2026.

Transparency log

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

Download URL qiskit_fermions-0.4.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
dd92e36e252565c63382835fa457ac3a253af53c952aff4c5dc6efa6645b19db
BLAKE2b-256 checksum
How to use checksums
e3655a962a08094a5ebeab5ba59236f48e828048c94afd54a06b21ebf2442def
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 Nov 4, 2026.

Transparency log

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

Download URL qiskit_fermions-0.4.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
12f1827017c81418e7282a8ba5d43da765ce1063ec92b47f33a95d179b8f4e5f
BLAKE2b-256 checksum
How to use checksums
0f5d6c56b6ae4405152dd8573b0ff3d39958c7617d8ce75bb2adb1c3e16f81a9
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 Nov 4, 2026.

Transparency log

Security for qiskit-fermions 0.4.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.4.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 Nov 4, 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