One reason we expect quantum computers to offer advantages is that simulating them classically becomes exponentially costly as systems grow. Exact classical simulations cannot match quantum hardware at scale, but they’re still essential for building, testing, and validating quantum workloads. We use them to prototype algorithms, explore their behavior at tractable problem sizes, and generate benchmarks for real quantum hardware. As quantum hardware and algorithms advance, we need faster, more capable verification tools to match their pace.

To meet this growing demand, we developed ffsim, an open-source Python library designed for simulating quantum circuits modeling fermions—the particles that make up atoms, molecules, and materials. ffsim exploits symmetries in these systems to greatly reduce the cost of simulation compared to a general-purpose quantum circuit simulator. Through its integration with Qiskit, ffsim can also simulate a wide class of quantum circuits with similar symmetries, even if they are unrelated to fermions.

In this blog, we provide a high-level overview of the ffsim library. If you’re interested to learn more, you’ll find additional details in our preprint on arXiv.

Why build a dedicated fermionic simulator?

There are many powerful general-purpose simulators that can represent any quantum circuit, from fermionic models to applications in optimization or machine learning. But that flexibility comes at a fundamental cost.

To represent a system with nn qubits, the simulator must store a full state vector—the mathematical object that encodes the system’s quantum state—of dimension 2n2^n. For the fermionic systems that make up molecules and materials, that’s an enormous waste of computational resources. These systems almost always conserve two key symmetries: the total particle number, and the zz component of spin. As a result, the physically meaningful states occupy only a small corner of the full Hilbert space of all possible quantum states. ffsim exploits this structure to drastically reduce the cost of fermionic simulation.

Instead of storing a 22N2^{2N}-dimensional state vector for 2N2N spin orbitals, it restricts the simulation to states with fixed numbers of spin-up electrons (NαN_\alpha) and spin-down electrons (NβN_\beta). This approach reduces the size of the problem to (NNα)×(NNβ)\binom{N}{N_\alpha} \times \binom{N}{N_\beta}. The scaling is still exponential, but with a much smaller prefactor that can make a meaningful difference in determining which systems we can simulate in practice.

Consider a two-dimensional Hubbard model on a 4×8 lattice, which maps to 64 qubits under standard fermion-to-qubit mappings. Representing this system with a general-purpose state vector simulation would require 256 EiB of memory—more than exists in all the world's supercomputers combined. However, at 1/8 filling—i.e., when only 1/8 of the spin orbitals are occupied by electrons—ffsim can simulate this system with only 19.3 GiB, allowing it to run on a single workstation.

What ffsim can do

ffsim's core function is to store a fermionic wave function and evolve it by applying fermionic quantum gates. It provides highly optimized implementations of a universal set of number-preserving fermionic gates—i.e., gates that conserve particle number—including orbital rotation, diagonal Coulomb evolution, number interaction, and more. State vectors are represented as standard NumPy arrays, and gate application follows a simple functional programming pattern:

rotated_vec = ffsim.apply_orbital_rotation(
    vec, orbital_rotation, norb=norb, nelec=nelec
)

Beyond basic state-vector evolution, ffsim offers additional features, including variational ansatzes like the LUCJ ansatz—commonly used in SQD calculations for chemistry—Hamiltonian time evolution via Trotter-Suzuki product formulas, efficient sampling of Slater determinants, and seamless integration with Qiskit and PySCF.

Together, these capabilities allow ffsim to function as a high-performance simulator within larger research workflows—giving you the ability to construct, refine, and benchmark circuits through repeated classical evaluation before running jobs on real quantum hardware.

For more details, see the full documentation.

Beyond fermions: simulating Hamming weight-preserving quantum circuits

Through its integration with Qiskit, ffsim's reach extends beyond explicitly fermionic simulation. Any Qiskit circuit composed entirely of Hamming weight-preserving gates—gates that leave the total number of 1s in the computational basis unchanged—can be simulated by ffsim, regardless of whether the circuit has anything to do with fermions.

Gates in this class include CPhaseGate, SwapGate, and XXPlusYYGate, among others. In practice, this allows ffsim to act as a high-performance simulator for a broader class of quantum circuits than its name might suggest. ffsim's flexibility also means you can easily integrate it into broader tooling ecosystems, where you'll be able to funnel circuits generated by different libraries or workflows into a common, symmetry-aware simulation backend.

Performance comparison with FQE and Qiskit Aer

To understand how ffsim performs in realistic application settings, we benchmarked it against FQE, the library most similar in purpose, and Qiskit Aer, a general-purpose quantum circuit simulator. The figure below shows runtimes for a representative workload: Trotterized time evolution of a molecular Hamiltonian in the double factorized representation, a common building block in quantum chemistry simulations.

ffsim is an order of magnitude faster than FQE for this task. Qiskit Aer lags behind both libraries at the larger system sizes, and cannot run the largest 16-orbital benchmark due to memory requirements.The 16 orbitals in this demonstration map to 32 qubits. All results were collected on a laptop.

The table below shows ffsim's speedups over FQE in a single-threaded configuration on an M1 MacBook.

Get started

As quantum software stacks continue to evolve, tools like ffsim will play an important role in enabling efficient classical validation of increasingly sophisticated circuit constructions, bridging the gap between algorithm design and quantum hardware execution.

We hope ffsim will serve as a useful tool for the quantum community. To get started, explore the documentation. We recommend beginning with State vectors and gates to learn the core concepts, or you can dive straight into a tutorial.

You can also browse the guides for help with specific tasks, or consult the API reference for detailed documentation of the library’s functions and classes. If you'd like to get involved with the development of ffsim, feel free to open an issue or pull request!