# 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: - [ffsim](https://qiskit-community.github.io/ffsim/) for the high-level ansatz operators and efficient simulation of fermionic circuits (see [Relationship to ffsim]()) ## Get started ![Schematic description of Qiskit Fermions](_images/overview.svg) 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](guides/overview.html.md) to help you get started. For an overview working through exactly the pipeline shown above, start with the [1D Fermi-Hubbard guide](guides/1d_fermi_hubbard.html.md). ## Use case examples Components of this package have been used in research related to the following papers: - The qDRIFT randomized circuit compilation in [1](#id4). - The fermion-to-qubit synthesis during the transpilation process in [2](#id5). ## 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](https://qiskit-community.github.io/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 [`FermionicCircuit`](stubs/qiskit_fermions.circuit.FermionicCircuit.html.md#qiskit_fermions.circuit.FermionicCircuit) 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 [`UCJ`](stubs/qiskit_fermions.circuit.library.UCJ.html.md#qiskit_fermions.circuit.library.UCJ) and [`UCC`](stubs/qiskit_fermions.circuit.library.UCC.html.md#qiskit_fermions.circuit.library.UCC) 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_`; see [`qiskit_fermions.protocols`](pydoc/qiskit_fermions.protocols.html.md#module-qiskit_fermions.protocols)), 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 the [Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/) for now. Building operators, mapping them and transpiling the resulting circuits need none of this and work everywhere. For the full picture, read the [ffsim relationship guide](guides/ffsim.html.md#ffsim-relationship-explanation). ### 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`](pydoc/qiskit_fermions.circuit.html.md#module-qiskit_fermions.circuit)) as well as transpiler passes ([`qiskit_fermions.transpiler`](pydoc/qiskit_fermions.transpiler.html.md#module-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](https://github.com/Qiskit/qiskit-fermions). The developer guide is located at [CONTRIBUTING.md](https://github.com/Qiskit/qiskit-fermions/blob/main/CONTRIBUTING.md) in the root of this project’s repository. By participating, you are expected to uphold Qiskit’s [code of conduct](https://github.com/Qiskit/qiskit/blob/main/CODE_OF_CONDUCT.md). ## Citing this package If you use this package in your research, use the [CITATION.bib](https://github.com/Qiskit/qiskit-fermions/blob/main/CITATION.bib) file in this project’s repository to cite the appropriate reference(s). ## License [Apache License 2.0](https://github.com/Qiskit/qiskit-fermions/blob/main/LICENSE.txt) ## Deprecation policy This package follows [semantic versioning](https://semver.org/). 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](release-notes.html.md#release-notes). ## References * **[1]** Samuele Piccinelli, et al., [Quantum chemistry with provable convergence via randomized sample-based Krylov quantum diagonalization](https://arxiv.org/abs/2508.02578v2), arXiv:2508.02578 [quant-ph]. * **[2]** Anthony Gandon, et al., [Stabilizer-based quantum simulation of fermion dynamics with local qubit encodings](https://arxiv.org/abs/2512.11418v2), arXiv:2512.11418 [quant-ph].