Installation

Installation#

Installation with conda#

The python interface can be easily installed with conda:

conda install -c conda-forge polyhedral-gravity-model

The python package on conda is parallelized with OpenMP. It is currently available for all operating systems (macOS, Linux, Windows), but only for x86_64 systems. Have a look at the Installation with pip. It also provides wheels for aarch64.

Installation with pip#

As a second option, you can also install the python interface with pip from PyPi:

pip install polyhedral-gravity

Binaries for the most common platforms are available on PyPI including Windows, Linux and macOS. For macOS and Linux, binaries for x86_64 and aarch64 are provided. In case pip uses the source distribution, please make sure that you have a C++17 capable compiler and CMake installed.

Installation & Build from source#

All these steps require a working C/C++ Compiler and CMake to be installed.

Build Python Package#

Use pip to install the python interface in your local python runtime. The module will be build using CMake. Just execute in repository root:

pip install .

To modify the build options (like parallelization) have a look at the Build Options for an overview of options. The pip installation will call CMake. To modify build options, just set them as environment variable before executing the pip install . command, e.g.:

export POLYHEDRAL_GRAVITY_PARALLELIZATION="TBB"

Build C++ library/ executable#

The C++ implementation relies on CMake as build system. The requirements (see below) are set-up automatically during the build process. Use the instructions below to build the project, from the repository’s root directory:

mkdir build
cd build
cmake .. <options>
cmake --build .

Have a look at Build Options for an overview of options available for the CMake build.

Build Options#

The available options are the following:

Name (Default)

Options

POLYHEDRAL_GRAVITY_PARALLELIZATION (CPP)

CPP = Serial Execution / OMP or TBB = Parallel Execution with OpenMP or Intel’s TBB

POLYHEDRAL_GRAVITY_LOGGING_LEVEL (INFO)

TRACE, DEBUG, INFO, WARN, ERROR, CRITICAL, OFF

BUILD_POLYHEDRAL_GRAVITY_DOCS (OFF)

Build this documentation

BUILD_POLYHEDRAL_GRAVITY_TESTS (ON)

Build the Tests

BUILD_POLYHEDRAL_GRAVITY_PYTHON_INTERFACE (ON)

Build the Python interface

Dependencies (automatically set-up)#

Dependencies (all of them are automatically set-up via CMake):

  • GoogleTest (1.15.2 or compatible), only required for testing

  • spdlog (1.13.0 or compatible), required for logging

  • tetgen (1.6 or compatible), required for I/O

  • yaml-cpp (0.8.0 or compatible), required for I/O

  • thrust (2.1.0 or compatible), required for parallelization and utility

  • xsimd (11.1.0 or compatible), required for vectorization of the atan(..)

  • pybind11 (2.12.0 or compatible), required for the Python interface, but not the C++ standalone

Build this documentation#

In order to build this documentation from source, you require the following dependencies:

  • Doxygen

  • Sphinx with the following plugins

    • breathe

    • sphinx-book-theme

  • The polyhedral_gravity Python Package needs to be installed

How you install the polyhedral_gravity Python Package is stated above. The other dependencies can be install them with your favorite package manager (e.g. conda, pip, brew, apt,…):

conda install doxygen sphinx breathe sphinx-book-theme

Build the documentation via CMake#

You can build the documentation locally using CMake by executing the following commands:

mkdir build && cd build
cmake .. -DBUILD_POLYHEDRAL_GRAVITY_DOCS=ON
cmake --build . --target Doxygen
cmake --build . --target Sphinx
open docs/sphinx/index.html

If you installed the Sphinx dependencies in a non-standard-path, e.g., a conda environment, you might need to help CMake finding it by specifying during the configure step -DCMAKE_PREFIX_PATH=$CONDA_PREFIX

Build the documentation invoking Sphinx#

You can also omit CMake and build the documentation locally in the following way:

cd docs
export BUILD_DOCS_CLI=1
make html # Alternatively: sphinx-build -M html . ./_build
open _build/html/index.html
Contents