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:
-
git clone --recursive git@github.com:glotzerlab/freud.git
Change to the repository directory:
cd freud
-
uv pip install .
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:
-
cd tests PYTHONPATH=../build python3 -m pytest
To build the documentation from source:
-
micromamba install sphinx furo nbsphinx jupyter_sphinx sphinxcontrib-bibtex sphinx-copybutton
-
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.
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.