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++, we recommend using CPM to manage the dependency. A simple CMake setup looks like this:

cmake_minimum_required(VERSION 3.15)
project(MyViennaPSProject)  

include(cmake/CPM.cmake) # Download from https://github.com/cpm-cmake/CPM.cmake/releases

CPMAddPackage(
    NAME ViennaPS
    VERSION 4.6.1
    GIT_REPOSITORY "https://github.com/ViennaTools/ViennaPS.git")

add_executable(my_executable main.cpp)
target_link_libraries(my_executable PRIVATE ViennaTools::ViennaPS)

ViennaPS 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.

ViennaPS 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.

Supported Operating Systems

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

System Requirements

C++20 Compiler with OpenMP support

Installing

The CMake configuration automatically checks if the dependencies are installed. If CMake is unable to find them, the dependencies will be built from source. 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/. Note that it is generally not recommended to install to system directories, since this can lead side effects with package managers.

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

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. For local builds, ViennaPS and ViennaLS should both be built locally. Mixing a local ViennaPS build with a ViennaLS PyPI wheel, or the other way around, is not supported.

Python installation scripts

For local Python installations, helper scripts are available in python/scripts.

Use install_ViennaPS.py when building ViennaPS locally. The script creates or reuses a virtual environment, installs a compatible local ViennaLS build, and then installs ViennaPS from the selected checkout:

python python/scripts/install_ViennaPS.py

When working from existing local checkouts, pass the ViennaLS source directory explicitly:

python python/scripts/install_ViennaPS.py --viennals-dir ../ViennaLS

GPU support is enabled by default in this script. On systems with a compatible CUDA toolkit, this builds ViennaPS and ViennaLS with GPU support, enabling GPU ray tracing in ViennaPS and the GPU BiCGSTAB solver used by the oxidation model. For a CPU-only setup, pass:

python python/scripts/install_ViennaPS.py --no-gpu

Integration in CMake projects

We recommend using CPM.cmake to consume this library.

Installation with CPM

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

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)

Shared Library

In order to save build time during development, dynamically linked shared libraries can be used if ViennaPS was built with them. This is done by precompiling the most common template specialisations. In order to use shared libraries, use

cmake -B build -DVIENNALS_PRECOMPILE_HEADERS=ON

If ViennaPS was built with shared libraries and you use ViennaPS in your project (see above), CMake will automatically link them to your project.