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

pixi add freud

Micromamba

micromamba install freud

Mamba

mamba install freud

PyPI

Install freud binaries from PyPI into a virtual environment:

uv

uv pip install freud-analysis

pip

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. uv

   Install with uv:

   uv pip install .
   

   CMake

   Install prerequisites and Build with CMake for development:

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

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

To run the tests:

1. Run tests:

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

To build the documentation from source:

1. Install prerequisites:

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

2. Build the documentation:

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

   sphinx-build -b html doc html
   

The sections below provide details on each of these steps.

Install prerequisites

freud requires a number of tools and libraries to build.

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

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

PYTHONPATH=../build python3 -m pytest

Build the documentation

Run Sphinx to build the HTML documentation:

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.