Installation

freud binaries are available on conda-forge and PyPI. You can also compile freud from source.

Binaries

conda-forge package

freud is available on conda-forge for the linux-64, osx-64, osx-arm64 and win-64 architectures:

pixi add freud

micromamba install freud

mamba install freud

PyPI

Install freud binaries from PyPI into a virtual environment:

uv pip install freud-analysis

python3 -m pip install freud-analysis

Compile from source

To build freud from source:

  1. Obtain the source:

    git clone --recursive git@github.com:glotzerlab/freud.git

  2. Change to the repository directory:

    cd freud

  3. Install with uv:

    uv pip install .

    To Run tests:

    cd tests
python3 -m pytest

    Install prerequisites and Build with CMake for development:

    eval "$(pixi shell-hook --environment py314)"

    cmake -B build -S . -GNinja
cd build
ninja

    To Run tests:

    cd ../tests
PYTHONPATH=../build python3 -m pytest

The sections below provide details on each of these steps.

Install prerequisites

freud requires a number of tools and libraries to build. You can use the provided pixi.toml to activate a Pixi environment with all of these installed. If you use another environment provider, install the following tools and packages:

General requirements:

  • A C++17 compliant compiler.

  • CMake >= 3.15.0

  • Intel Threading Building Blocks >= 2019.7

  • nanobind >= 2.0.0

  • NumPy >= 1.19.0

  • Python >= 3.12

  • scikit-build-core

To execute unit tests:

  • dynasor (optional)

  • gsd

  • matplotlib

  • pytest

  • rowan

  • scipy

  • sympy

To build the documentation:

  • sphinx

  • nbsphinx

  • furo

  • jupyter_sphinx

  • sphinxcontrib-bibtex

  • sphinx-copybutton

Obtain the source

Clone using Git:

git clone --recursive git@github.com:glotzerlab/freud.git

Release tarballs are also available on the GitHub release pages.

See also

See the git book to learn how to work with Git repositories.

Install with uv

Use uv to install the Python module into your virtual environment:

cd {{ path/to/freud/repository }}

uv pip install .

To perform incremental builds, install the prerequisites first, then run:

uv pip install --no-deps --no-build-isolation --force-reinstall -C build-dir=$PWD/build .

You may find using CMake directly more effective for incremental builds (see the next section).

Build with CMake for development

freud also provides CMake scripts for development and testing that build a functional Python module in the build directory. First, configure the build with cmake:

cd {{ path/to/freud/repository }}

cmake -B build -S . -GNinja

Then, build the code:

cd build
ninja

Execute ninja to rebuild after you modify the code. ninja will automatically reconfigure as needed.

Tip

Pass the following options to cmake to optimize the build for your processor: -DCMAKE_CXX_FLAGS=-march=native -DCMAKE_C_FLAGS=-march=native.

Warning

When using a conda-forge environment for development, make sure that the environment does not contain clang, gcc, or any other compiler or linker. These interfere with the native compilers on your system and will result in compiler errors when building, linker errors when running, or segmentation faults.

Run tests

Note

You must first Obtain the source before you can run the tests.

Use pytest to execute unit tests:

cd {{ path/to/freud/repository }}
cd tests

python3 -m pytest

PYTHONPATH=../build python3 -m pytest

Build the documentation (optional)

Run Sphinx to build the HTML documentation:

cd {{ path/to/freud/repository }}
cd doc
make html

cd {{ path/to/freud/repository }}
PYTHONPATH=build sphinx-build -b html doc/source html

Open the file html/index.html in your web browser to view the documentation.

Tip

Add the sphinx options -a -n -W -T --keep-going to produce docs with consistent links in the side panel and provide more useful error messages.

Important

You must clone the freud GitHub repository to build the documentation.