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

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.1
File Size Uploaded Provenance Actions
qiskit_fermions-0.3.1.tar.gz 178.5 kB With provenance Details for qiskit_fermions-0.3.1.tar.gz

Built distributions (wheels)

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

Total release size: 9.0 MB

Release files / qiskit_fermions-0.3.1.tar.gz

Download URL qiskit_fermions-0.3.1.tar.gz
Size 178.5 kB
Tags Source
SHA-256 checksum
How to use checksums
f9c80170e26070fb54b85b5c34a694928d8997d44003befe1dd674b6d467723a
BLAKE2b-256 checksum
How to use checksums
5801a4a66846a2271342c422f9098358e613cefe20669ff3908c87e0576c9648
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 26, 2026.

Transparency log

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

Download URL qiskit_fermions-0.3.1-cp311-abi3-win_amd64.whl
Size 1.6 MB
Tags CPython 3.11 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
d327aad2506fda25ec48c67aaaca8a2a96efff78df41c8b76855dff9c34bb7d0
BLAKE2b-256 checksum
How to use checksums
4e7d7b1f71d33b32edc3f12ccca33dee182e1b37e4ae5171ec5f2f965271ffe0
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 26, 2026.

Transparency log

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

Download URL qiskit_fermions-0.3.1-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
05cc5d128f5b0616b7aec3ab3f774bdd4a37f19a0fde3f4b4a1444741d5b8719
BLAKE2b-256 checksum
How to use checksums
ae61ce22c183ec6a59e6d716efa71e23a6577cff8b8d810c2d8b206df6f01f07
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 26, 2026.

Transparency log

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

Download URL qiskit_fermions-0.3.1-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
868c5e79f92c62a3264a419a1bee764b3b95cde9b32d785bb30a12c457954dca
BLAKE2b-256 checksum
How to use checksums
e0e4000fff691bca43725775da1b61d3f783139e3109b4c3c77b9c2bfbb05ad4
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 26, 2026.

Transparency log

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

Download URL qiskit_fermions-0.3.1-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
27ebab8ff64b74ea90a2311dd7a1d5828a00009a474ff9e4ea5d81dd226d5e94
BLAKE2b-256 checksum
How to use checksums
205bde4ae02e461a2a7698f11c2d04c68bc397e912263c88f804090736cd2110
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 26, 2026.

Transparency log

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

Download URL qiskit_fermions-0.3.1-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
3d58b08d51afc249233e531635cfbb4e7c1c370073eafb0ceea0a175a24c21e6
BLAKE2b-256 checksum
How to use checksums
d163d7fafc8e239cfebea450813e88cdcb17d8d7ec558f8f1add7021e5b576e1
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 26, 2026.

Transparency log

Security for qiskit-fermions 0.3.1

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.1.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 26, 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