Installation

Installing freud

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

Install via conda

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

mamba install freud

Install via pip

To install freud is also available from PyPI. To install freud into a non-conda virtual environment, execute:

uv pip install freud-analysis

or

python3 -m pip install freud-analysis

Compile from source

The following are required for building and installing freud from source:

Note

Depending on the generator you are using, you may require a newer version of CMake. In particular, Visual Studio 2019 requires CMake >= 3.14.0. For more information on specific generators, see the CMake generator documentation.

The freud library uses scikit-build and CMake to handle the build process itself, while the other requirements are required for compiling code in freud. These requirements can be met by installing the following packages from the conda-forge channel:

mamba install conda-forge tbb tbb-devel numpy cython scikit-build cmake

All requirements other than TBB can also be installed via the Python Package Index

uv pip install numpy cython scikit-build cmake

Wheels for tbb and tbb-devel exist on PyPI, but only for certain operating systems, so your mileage may vary. For non-conda users, we recommend using OS-specific package managers (e.g. Homebrew for Mac) to install TBB. As in the snippets above, it may be necessary to install both both a TBB and a “devel” package in order to get both the headers and the shared libraries.

The code that follows builds freud and installs it for all users (append --user if you wish to install it to your user site directory):

git clone --recurse-submodules https://github.com/glotzerlab/freud.git
cd freud
uv pip install .

CMake Options

The scikit-build tool allows setup.py to accept three different sets of options separated by --, where each set is provided directly to scikit-build, to CMake, or to the code generator of choice, respectively. For example, the command python setup.py build_ext --inplace -- -DCOVERAGE=ON -G Ninja -- -j 4 tell scikit-build to perform an in-place build, it tells CMake to turn on the COVERAGE option and use Ninja for compilation, and it tells Ninja to compile with 4 parallel threads. For more information on these options, see the scikit-build docs.

In addition to standard CMake flags, the following CMake options are available for freud:

--COVERAGE

Build the Cython files with coverage support to check unit test coverage.

The freud CMake configuration also respects the following environment variables (in addition to standards like CMAKE_PREFIX_PATH).

TBBROOT

The root directory where TBB is installed. Useful if TBB is installed in a non-standard location or cannot be located for some other reason. This variable is set by the tbbvars.sh script included with TBB when building from source.

TBB_INCLUDE_DIR

The directory where the TBB headers (e.g. tbb.h) are located. Useful if TBB is installed in a non-standard location or cannot be located for some other reason.

Note

freud makes use of git submodules. To manually update git submodules, execute:

git submodule update --init --recursive

Unit Tests

The unit tests for freud are included in the repository and are configured to be run using the Python pytest library:

# Run tests from the tests directory
cd tests
python -m pytest .

Note that because freud is designed to require installation to run (i.e. it cannot be run directly out of the build directory), importing freud from the root of the repository will fail because it will try and import the package folder. As a result, unit tests must be run from outside the root directory if you wish to test the installed version of freud. If you want to run tests within the root directory, you can instead build freud in place:

# Run tests from the tests directory
python setup.py build_ext --inplace

This build will place the necessary files alongside the freud source files so that freud can be imported from the root of the repository.

Documentation

The documentation for freud is hosted online at ReadTheDocs. You may also build the documentation yourself.

Building the documentation

The following are required for building freud documentation:

You can install these dependencies using conda:

mamba install sphinx furo nbsphinx jupyter_sphinx sphinxcontrib-bibtex sphinx-copybutton

or pip:

uv pip install sphinx sphinx-rtd-theme nbsphinx jupyter-sphinx sphinxcontrib-bibtex sphinx-copybutton

To build the documentation, run the following commands in the source directory:

cd doc
make html
# Then open build/html/index.html

To build a PDF of the documentation (requires LaTeX and/or PDFLaTeX):

cd doc
make latexpdf
# Then open build/latex/freud.pdf