Skip to main content

ffsim

ffsim is a software library for simulating fermionic quantum circuits that conserve particle number and the z component of spin. This category includes many quantum circuits used for quantum chemistry simulations. By exploiting the symmetries and using specialized algorithms, ffsim can simulate these circuits much faster than a generic quantum circuit simulator.

Documentation

Documentation is located at the project website. You might also be interested in the paper about ffsim.

Installation

You can install ffsim using pip:

pip install ffsim

See the installation instructions for more details, including instructions for installing from source and running ffsim in a container.

Get started

Visit State vectors and gates to start learning ffsim's core concepts, or jump straight into a tutorial. Check out the guides for help with specific tasks, or visit the API reference for detailed documentation of all function and classes available in the library.

Multithreading

Some ffsim functions implemented in Rust use multithreading. The number of threads can be controlled using the environment variable RAYON_NUM_THREADS. For example, to disable multithreading, set this variable as RAYON_NUM_THREADS=1.

Code example

import numpy as np
import pyscf

import ffsim

# Generate the Hamiltonian for an N2 molecule using PySCF and ffsim's wrapper for it
mol = pyscf.gto.Mole()
mol.build(atom=[["N", (0, 0, 0)], ["N", (1.0, 0, 0)]], basis="6-31g", symmetry="Dooh")
scf = pyscf.scf.RHF(mol).run()
mol_data = ffsim.MolecularData.from_scf(scf, active_space=range(4, mol.nao_nr()))
norb, nelec = mol_data.norb, mol_data.nelec
hamiltonian = mol_data.hamiltonian

# Convert the Hamiltonian to a SciPy LinearOperator
linop = ffsim.linear_operator(hamiltonian, norb=norb, nelec=nelec)

# Generate a random orbital rotation
orbital_rotation = ffsim.random.random_unitary(norb, seed=1234)

# Create the Hartree-Fock state and apply the orbital rotation to it
vec = ffsim.hartree_fock_state(norb, nelec)
vec = ffsim.apply_orbital_rotation(vec, orbital_rotation, norb=norb, nelec=nelec)

# Compute the energy of the state
energy = np.vdot(vec, linop @ vec).real
print(energy)  # prints -104.17181289596

Citing ffsim

You can cite ffsim using the following BibTeX:

@misc{sung2026ffsim,
      title={ffsim: Faster simulation of fermionic quantum circuits},
      author={Kevin J. Sung and Inho Choi and Mirko Amico and Bartholomew Andrews and Esra Ayantuna and Yukio Kawashima and Wan-Hsuan Lin and David Omanovic and Samuele Piccinelli and Javier Robledo Moreno and Abdullah Ash Saki and James Shee and Soyoung Shin and Minh C. Tran and Kento Ueda and Haimeng Zhang and Mario Motta},
      year={2026},
      eprint={2605.03123},
      archivePrefix={arXiv},
      primaryClass={quant-ph},
      url={https://arxiv.org/abs/2605.03123},
}

Developer guide

See the developer guide for instructions on contributing code to ffsim.

Metadata

Release files for ffsim 0.0.86

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ffsim 0.0.86
File Size Uploaded Provenance Actions
ffsim-0.0.86.tar.gz 2.6 MB With provenance Details for ffsim-0.0.86.tar.gz

Built distributions (wheels)

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

Total release size: 5.5 MB

Release files / ffsim-0.0.86.tar.gz

Download URL ffsim-0.0.86.tar.gz
Size 2.6 MB
Tags Source
SHA-256 checksum
How to use checksums
f8c860f6501d926e0b879d65e35e530d8c8941b8f0a467c0d4a878952da102e6
BLAKE2b-256 checksum
How to use checksums
89b166172513dc29cfde58ce964935512cd57ae4e90d8084fa21626220b73ef2
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 5, 2026.

Transparency log

Release files / ffsim-0.0.86-cp311-abi3-win_amd64.whl

Download URL ffsim-0.0.86-cp311-abi3-win_amd64.whl
Size 625.3 kB
Tags CPython 3.11 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
2a31028f913b6deea06f37576654348650277080c4c13a20e24a0a5a94c0eb05
BLAKE2b-256 checksum
How to use checksums
b651e0f9d17edcc4a4d97c83e1651c0592314533a3e7babab0a7bef3e27d7452
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 5, 2026.

Transparency log

Release files / ffsim-0.0.86-cp311-abi3-manylinux_2_28_x86_64.whl

Download URL ffsim-0.0.86-cp311-abi3-manylinux_2_28_x86_64.whl
Size 784.5 kB
Tags CPython 3.11 Linux glibc 2.28+ x86-64 abi3
SHA-256 checksum
How to use checksums
1c6816115efae49dee23d4b28c0668f312aefd77871d4c01de69a85d63b25b1b
BLAKE2b-256 checksum
How to use checksums
66fa043b4aca66a87f197d92f1135653e0f4784dfd2f4770f5ba5b22edd226f2
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 5, 2026.

Transparency log

Release files / ffsim-0.0.86-cp311-abi3-manylinux_2_28_aarch64.whl

Download URL ffsim-0.0.86-cp311-abi3-manylinux_2_28_aarch64.whl
Size 771.7 kB
Tags CPython 3.11 Linux glibc 2.28+ ARM64 abi3
SHA-256 checksum
How to use checksums
4dbe7676d695eb6607b061e84e842d455065c602f70117f9f2691169b92bb9c8
BLAKE2b-256 checksum
How to use checksums
e0dcda6f44880ad7b4e31b7f4d107ce4c796649ff108298b5c1303e2e25bc8b8
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 5, 2026.

Transparency log

Release files / ffsim-0.0.86-cp311-abi3-macosx_11_0_arm64.whl

Download URL ffsim-0.0.86-cp311-abi3-macosx_11_0_arm64.whl
Size 731.8 kB
Tags CPython 3.11 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
031c4e767e8e8652768f649835d67524cd179d73f2baf0aa656a86a38eb9c04e
BLAKE2b-256 checksum
How to use checksums
f2f4cbf28019ed95acee99bd512daa40031aa3ede0ced188a4a41f81ead336e0
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 5, 2026.

Transparency log

Security for ffsim 0.0.86

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 5 files in this release have been uploaded with provenance metadata.

Select from 5 files

Attestation for ffsim-0.0.86.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 5, 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.

Release history Release notifications | RSS feed

This release

0.0.86 This release

5 release files Full provenance

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