Installation¶
Installing freud¶
You can either install freud via conda or compile it from source.
Install via conda¶
The code below will install freud from conda-forge.
conda install -c conda-forge freud
Compile from source¶
The following are required for installing freud:
- Python (2.7, 3.5, 3.6)
- NumPy
- Intel Threading Building Blocks (TBB)
The following are optional for installing freud:
- Cython: The freud repository contains Cython-generated
*.cpp
files in thefreud/
directory that can be used directly. However, Cython is necessary if you wish to recompile these files.
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://bitbucket.org/glotzer/freud.git
cd freud
python setup.py install
You can also build freud in place so that you can run from within the folder:
# Run tests from the tests directory
python setup.py build_ext --inplace
Building freud in place has certain advantages, since it does not affect your Python behavior except within the freud directory itself (where freud can be imported after building). Additionally, due to limitations inherent to the distutils/setuptools infrastructure, building extension modules can only be parallelized using the build_ext subcommand of setup.py, not with install. As a result, it will be faster to manually run build_ext and then install (which normally calls build_ext under the hood anyway) the built packages. In general, the following options are available for setup.py in addition to the standard setuptools options (notes are included to indicate which options are only available for specific subcommands such as build_ext):
- --PRINT-WARNINGS
- Specify whether or not to print compilation warnings resulting from the build even if the build succeeds with no errors.
- --ENABLE-CYTHON
- Rebuild the Cython-generated C++ files. If there are any unexpected issues with compiling the C++ shipped with the build, using this flag may help. It is also necessary any time modifications are made to the Cython files.
- -j
- Compile in parallel. This affects both the generation of C++ files from Cython files and the subsequent compilation of the source files. In the latter case, this option controls the number of Python modules that will be compiled in parallel.
- --TBB-ROOT
- The root directory where TBB is installed. Useful if TBB is installed in a non-standard location or cannot be located by Python for some other reason. Note that this information can also be provided using the environment variable TBB_ROOT. The options –TBB-INCLUDE and –TBB-LINK will take precedence over –TBB-ROOT if both are specified.
- --TBB-INCLUDE
- 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 by Python for some other reason. Note that this information can also be provided using the environment variable TBB_ROOT. The options –TBB-INCLUDE and –TBB-LINK will take precedence over –TBB-ROOT if both are specified.
- --TBB-LINK
- The directory where the TBB shared library (e.g. libtbb.so or libtbb.dylib) is located. Useful if TBB is installed in a non-standard location or cannot be located by Python for some other reason. Note that this information can also be provided using the environment variable TBB_ROOT. The options –TBB-INCLUDE and –TBB-LINK will take precedence over –TBB-ROOT if both are specified.
The following additional arguments are primarily useful for developers:
- --COVERAGE
- Build the Cython files with coveragerc support to check unit test coverage.
- --NTHREAD
- Specify the number of threads to allocate to compiling each module. This option is primarily useful for rapid development, particularly when all changes are in one module. While the -j option will not help parallelize this case, this option allows compilation of multiple source files belonging to the same module in parallel.
Note
freud makes use of submodules. If you ever wish to manually update these, you can execute:
git submodule update --init
Unit Tests¶
The unit tests for freud are included in the repository and are configured to be run using the Python unittest
library:
# Run tests from the tests directory
cd tests
python -m unittest discover .
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, but you may also build the documentation yourself:
Building the documentation¶
The following are required for building freud documentation:
You can install sphinx using conda
conda install sphinx
or from PyPi
pip install sphinx
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