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:
- ffsim for the high-level ansatz operators and efficient simulation of fermionic circuits (see Relationship to ffsim)
Documentation for this package is available on IBM Quantum Platform.
You can also preview the docs of the development branch on Github pages.
Refer to the C installation instructions.
Install this package via pip, when possible:
pip install 'qiskit-fermions'For more installation information, refer to these installation instructions.
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.
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.
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.
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.
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).
- 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
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.
If you use this package in your research, use the CITATION.bib file in this project’s repository to cite the appropriate reference(s).
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.
Footnotes
-
Samuele Piccinelli, et al., Quantum chemistry with provable convergence via randomized sample-based Krylov quantum diagonalization, arXiv:2508.02578 [quant-ph]. ↩
-
Anthony Gandon, et al., Stabilizer-based quantum simulation of fermion dynamics with local qubit encodings, arXiv:2512.11418 [quant-ph]. ↩