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. Execute one of the following commands to install freud:

micromamba install freud

OR

mamba install freud

PyPI

Use uv or pip to install freud binaries from PyPI into a virtual environment:

uv pip install freud-analysis

OR

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 .
    
  4. OR Install prerequisites and Build with CMake for development:

    micromamba install cmake ninja numpy python tbb-devel nanobind scikit-build-core gsd matplotlib pytest rowan scipy sympy
    
    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:

    micromamba install sphinx furo nbsphinx jupyter_sphinx sphinxcontrib-bibtex sphinx-copybutton
    
  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.9

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