diff --git a/.gitignore b/.gitignore index 15c86627d..6599779e6 100644 --- a/.gitignore +++ b/.gitignore @@ -22,3 +22,4 @@ freud/*.cpp freud/*.cxx freud/*.dylib freud/*.so +html diff --git a/doc/source/gettingstarted/installation.rst b/doc/source/gettingstarted/installation.rst index f8d0faba9..248a01f9a 100644 --- a/doc/source/gettingstarted/installation.rst +++ b/doc/source/gettingstarted/installation.rst @@ -1,36 +1,40 @@ .. _installation: -============ Installation ============ -Installing freud -================ - **freud** binaries are available on conda-forge_ and PyPI_. You can also compile **freud** from source. -Install via conda ------------------ +Binaries +-------- + +conda-forge package +^^^^^^^^^^^^^^^^^^^ **freud** is available on conda-forge_ for the *linux-64*, *osx-64*, *osx-arm64* and *win-64* -architectures. Install with: +architectures. Execute one of the following commands to install **freud**: -.. code:: bash +.. code-block:: bash + + micromamba install freud + +**OR** + +.. code-block:: bash mamba install freud -Install via pip ------------------ +PyPI +^^^^ -To install **freud** is also available from PyPI_. To install **freud** into a *non-conda* virtual -environment, execute: +Use **uv** or **pip** to install **freud** binaries from PyPI_ into a virtual environment: .. code:: bash uv pip install freud-analysis -or +**OR** .. code:: bash @@ -42,147 +46,211 @@ or Compile from source ------------------- -The following are **required** for building and installing **freud** from source: +To build **freud** from source: -- A C++17-compliant compiler -- `Python `__ (>=3.9) -- `NumPy `__ (>=1.19) -- `Intel Threading Building Blocks `__ (>=2019.7) -- `Cython `__ (>=3.0.2) -- `scikit-build `__ (>=0.10.0) -- `CMake `__ (>=3.13.0) +1. `Obtain the source`_: -.. note:: + .. code-block:: bash - 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 `__. + git clone --recursive git@github.com:glotzerlab/freud.git -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 `__: +2. Change to the repository directory:: -.. code-block:: bash + cd freud - mamba install conda-forge tbb tbb-devel numpy cython scikit-build cmake +3. `Install with uv`_:: -All requirements other than TBB can also be installed via the `Python Package Index `__ + uv pip install . -.. code-block:: bash +4. **OR** `Install prerequisites`_ and `Build with CMake for development`_: - uv pip install numpy cython scikit-build cmake + .. code-block:: bash -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. + micromamba install cmake ninja numpy python tbb-devel nanobind scikit-build-core gsd matplotlib pytest rowan scipy sympy -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): + .. code-block:: bash + + cmake -B build -S . -GNinja + cd build + ninja -.. code-block:: bash +To run the tests: - git clone --recurse-submodules https://github.com/glotzerlab/freud.git - cd freud - uv pip install . +1. `Run tests`_:: -CMake Options -+++++++++++++ + cd tests + PYTHONPATH=../build python3 -m pytest -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 `__. +To build the documentation from source: -In addition to standard CMake flags, the following CMake options are available for **freud**: +1. `Install prerequisites`_:: -.. glossary:: + micromamba install sphinx furo nbsphinx jupyter_sphinx sphinxcontrib-bibtex sphinx-copybutton - \--COVERAGE - Build the Cython files with coverage support to check unit test coverage. +2. `Build the documentation`_: + .. code-block:: bash -The **freud** CMake configuration also respects the following environment variables (in addition to standards like ``CMAKE_PREFIX_PATH``). + cd {{ path/to/freud/repository }} + + .. code-block:: bash -.. glossary:: + sphinx-build -b html doc html - 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. +The sections below provide details on each of these steps. - 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. +.. _Install prerequisites: -.. note:: +Install prerequisites +^^^^^^^^^^^^^^^^^^^^^ - **freud** makes use of git submodules. To manually update git submodules, execute: +**freud** requires a number of tools and libraries to build. - .. code-block:: bash +**General requirements:** - git submodule update --init --recursive +- 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** -Unit Tests -========== +**To execute unit tests:** -The unit tests for **freud** are included in the repository and are configured to be run using the Python :mod:`pytest` library: +- **dynasor** (optional) +- **gsd** +- **matplotlib** +- **pytest** +- **rowan** +- **scipy** +- **sympy** + +.. _Obtain the source: + +Obtain the source +^^^^^^^^^^^^^^^^^ + +Clone using Git_: .. code-block:: bash - # Run tests from the tests directory - cd tests - python -m pytest . + git clone --recursive git@github.com:glotzerlab/freud.git + +Release tarballs are also available on the `GitHub release pages`_. + +.. seealso:: + + See the `git book`_ to learn how to work with `Git`_ repositories. + +.. _GitHub release pages: https://github.com/glotzerlab/freud/releases/ +.. _git book: https://git-scm.com/book +.. _Git: https://git-scm.com/ + + +.. _Install with uv: + +Install with uv +^^^^^^^^^^^^^^^^ -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: +Use **uv** to install the Python module into your virtual environment: .. code-block:: bash - # Run tests from the tests directory - python setup.py build_ext --inplace + cd {{ path/to/freud/repository }} -This build will place the necessary files alongside the **freud** source files so that **freud** can be imported from the root of the repository. +.. code-block:: bash + + uv pip install . + +To perform incremental builds, `install the prerequisites first `_, then run: + +.. code-block:: bash + + uv pip install --no-deps --no-build-isolation --force-reinstall -C build-dir=$PWD/build . -Documentation -============= +You may find using `CMake`_ directly more effective for incremental builds (see the next section). -The documentation for **freud** is `hosted online at ReadTheDocs `_. -You may also build the documentation yourself. +.. Build with CMake for development: -Building the documentation --------------------------- +Build with CMake for development +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The following are **required** for building **freud** documentation: +**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``: -- `Sphinx `_ -- `The furo Sphinx Theme `_ -- `nbsphinx `_ -- `jupyter_sphinx `_ -- `sphinxcontrib-bibtex `_ -- `sphinx-copybutton `_ +.. code-block:: bash -You can install these dependencies using conda: + cd {{ path/to/freud/repository }} .. code-block:: bash - mamba install sphinx furo nbsphinx jupyter_sphinx sphinxcontrib-bibtex sphinx-copybutton + cmake -B build -S . -GNinja -or pip: +Then, build the code: .. code-block:: bash - uv pip install sphinx sphinx-rtd-theme nbsphinx jupyter-sphinx sphinxcontrib-bibtex sphinx-copybutton + 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. + +.. _CMake: https://cmake.org/ +.. _Ninja: https://ninja-build.org/ + + +Run tests +^^^^^^^^^ + +.. note:: + + You must first `Obtain the source`_ before you can run the tests. + +Use `pytest`_ to execute unit tests: + +.. code-block:: bash -To build the documentation, run the following commands in the source directory: + cd {{ path/to/freud/repository }} + cd tests .. code-block:: bash - cd doc - make html - # Then open build/html/index.html + PYTHONPATH=../build python3 -m pytest + +.. _pytest: https://docs.pytest.org/ + -To build a PDF of the documentation (requires LaTeX and/or PDFLaTeX): +.. _Build the documentation: + +Build the documentation +^^^^^^^^^^^^^^^^^^^^^^^ + +Run `Sphinx`_ to build the HTML documentation: .. code-block:: bash - cd doc - make latexpdf - # Then open build/latex/freud.pdf + PYTHONPATH=build sphinx-build -b html doc/source html + +Open the file :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. + +.. _Sphinx: https://www.sphinx-doc.org/ +