Installing the Library

Quick Start

To install ViennaPS for Python, simply run:

pip install ViennaPS

If there is no pre-built package available for your operating system, you can build the package yourself using the instructions below. To use ViennaPS in C++, clone the repository and follow the installation steps below.

Supported Operating Systems

Windows (Visual Studio)
Linux (g++ / clang)
macOS (XCode)

System Requirements

C++17 Compiler with OpenMP support

Installing

ViennaLS uses VTK as dependency which can be installed beforehand to save some time when building the dependencies. On Linux based systems, it can be installed using the package manager: sudo apt install libvtk9.1 libvtk9-dev. On macOS, one can use Homebrew to install it: brew install vtk.

ViennaRay uses Embree as dependency which can be installed beforehand to save some time when building the dependencies. On Linux based systems, it can be installed using the package manager: sudo apt install libembree-dev. If you are using an Ubuntu version older than 24, the installed package will be Embree version 3, and you must additionally pass VIENNARAY_EMBREE_VERSION=3 to the CMake options, e.g., cmake -B build -G Ninja -D VIENNARAY_EMBREE_VERSION=3 On macOS, you can install Embree using Homebrew with the command: brew install embree.

The CMake configuration automatically checks if the dependencies are installed. If CMake is unable to find them, the dependencies will be built from source with the buildDependencies target. Notably, ViennaPS operates as a header-only library, eliminating the need for a formal installation process. Nonetheless, we advise following the outlined procedure to neatly organize and relocate all header files to a designated directory:

git clone https://github.com/ViennaTools/ViennaPS.git
cd ViennaPS

cmake -B build -G Ninja && cmake --build build
cmake --install build --prefix "/path/to/your/custom/install/"

This will install the necessary headers and CMake files to the specified path. If --prefix is not specified, it will be installed to the standard path for your system, usually /usr/local/ .

The -G Ninja option can be omitted if you prefer to use Unix Makefiles as the build system. However, this can potentially lead to conflicts when later installing the Python package using the pip installer, as pip always employs Ninja as the build system.

Building the Python package locally

In order to build the Python bindings, the pybind11 library is required. On Linux based system (Ubuntu/Debian), pybind11 can be installed via the package manager: sudo apt install pybind11-dev. For macOS, the installation via Homebrew is recommended: brew install pybind11. The ViennaPS Python package can be built and installed using the pip command:

git clone https://github.com/ViennaTools/ViennaPS.git
cd ViennaPS

pip install .

Some functionalities of the ViennaPS Python module only work in combination with the ViennaLS Python module. It is therefore necessary to additionally install the ViennaLS Python module on your system. Instructions to do so can be found in the ViennaLS Git Repository.

Integration in CMake projects

We recommend using CPM.cmake to consume this library.

Installation with CPM

CPMAddPackage("gh:viennatools/viennaps@3.1.0")

With a local installation

In case you have ViennaPS installed in a custom directory, make sure to properly specify the CMAKE_PREFIX_PATH.

  list(APPEND CMAKE_PREFIX_PATH "/your/local/installation")

  find_package(ViennaPS)
  target_link_libraries(${PROJECT_NAME} PUBLIC ViennaTools::ViennaPS)