Installation¶
ffsim is supported directly on Linux and macOS.
ffsim is not supported directly on Windows. Windows users have two main options:
Use Windows Subsystem for Linux (WSL). WSL provides a Linux environment where ffsim can be pip installed from PyPI or from source.
Use ffsim within Docker. See Use within Docker.
Pip install¶
ffsim is available on PyPI. You can install it by running
pip install ffsim
For improved performance on x86 systems, considering installing from source.
GPU acceleration¶
Some functions in ffsim are implemented with JAX, which uses the CPU by default. If you have an NVIDIA GPU, you can install the appropriate extra to let JAX use the GPU instead:
pip install "ffsim[cuda12]" # for CUDA 12
pip install "ffsim[cuda13]" # for CUDA 13
These extras install a CUDA-enabled JAX; no changes to your code are required, because JAX selects the GPU automatically once the plugin is present. The GPU wheels are only published for Linux.
The speedup grows with the number of orbitals, and is negligible below roughly 16 orbitals, where the cost is dominated by kernel launch overhead rather than by the linear algebra. To force the CPU path for comparison, set the environment variable JAX_PLATFORMS=cpu.
Install from source¶
You can use pip to install ffsim from source. For example:
git clone https://github.com/qiskit-community/ffsim.git
cd ffsim
pip install .
Installing from source may improve performance on x86 systems because the Rust extensions in the PyPI wheels are compiled with -C target-cpu=x86-64, which targets the baseline x86-64 instruction set for broad compatibility. When you build from source, ffsim is configured to compile its Rust extensions with -C target-cpu=native, so the Rust compiler can emit optimized instructions (e.g., AVX2, AVX-512) for your specific CPU.
Similarly, you can install PySCF from source with -DBUILD_MARCH_NATIVE=ON to enable CPU-specific optimizations in PySCF’s C extensions. See PySCF’s installation instructions for details.
Use within Docker¶
We provide a Dockerfile and a compose.yaml file, which you can use to build a Docker image with just a few simple commands:
git clone https://github.com/qiskit-community/ffsim.git
cd ffsim
docker compose build
docker compose up
Depending on your system configuration, you may need to type sudo before each docker command.
Once the container is running, navigate to http://localhost:58888 in a web browser to access the Jupyter Notebook interface.
The home directory includes a subdirectory named persistent-volume. All work you’d like to save should be placed in this directory, as it is the only one that will be saved across different container runs.