4 Getting Started

IPPL is configured with CMake. A minimal build needs a C++20 compiler, MPI, and Kokkos. FFT and solver chapters require builds with IPPL_ENABLE_FFT=ON and usually IPPL_ENABLE_SOLVERS=ON, but the first program does not need that stack.

4.1 Minimal program

#include "Ippl.h"

int main(int argc, char* argv[]) {
    ippl::initialize(argc, argv);

    *ippl::Info << "Hello from rank "
                << ippl::Comm->rank()
                << " of "
                << ippl::Comm->size()
                << ippl::endl;

    ippl::finalize();
    return 0;
}

4.2 Compile a small IPPL program

A minimal standalone program can be developed as a small CMake project. During early example development, the most robust pattern is to consume IPPL as a CMake subproject so that the example uses the same dependency configuration as the IPPL source tree.

Create hello_ippl.cpp:

#include "Ippl.h"

int main(int argc, char* argv[]) {
    ippl::initialize(argc, argv);

    *ippl::Info << "Hello from rank "
                << ippl::Comm->rank()
                << " of "
                << ippl::Comm->size()
                << ippl::endl;

    ippl::finalize();
    return 0;
}

Create CMakeLists.txt next to it:

cmake_minimum_required(VERSION 3.24)

project(ippl_hello LANGUAGES CXX)

set(IPPL_PLATFORMS "SERIAL" CACHE STRING "" FORCE)
set(IPPL_ENABLE_FFT OFF CACHE BOOL "" FORCE)
set(IPPL_ENABLE_SOLVERS OFF CACHE BOOL "" FORCE)
set(IPPL_ENABLE_TESTS OFF CACHE BOOL "" FORCE)
set(IPPL_ENABLE_UNIT_TESTS OFF CACHE BOOL "" FORCE)
set(Kokkos_VERSION "git.4.7.02" CACHE STRING "" FORCE)
set(IPPL_SOURCE_DIR "/workspaces/ippl" CACHE PATH "IPPL source tree")

add_subdirectory("${IPPL_SOURCE_DIR}" ippl-build)

add_executable(hello_ippl hello_ippl.cpp)
target_link_libraries(hello_ippl PRIVATE IPPL::ippl)

Configure, build, and run it inside the devcontainer:

cmake -S . -B build -G Ninja -DCMAKE_CXX_COMPILER=mpicxx
cmake --build build --target hello_ippl --parallel 2
mpiexec --oversubscribe -n 2 build/hello_ippl

Expected output:

Hello from rank 0 of 2
Hello from rank 1 of 2

For installed IPPL packages, the CMakeLists.txt becomes shorter:

cmake_minimum_required(VERSION 3.24)

project(ippl_hello LANGUAGES CXX)

find_package(IPPL REQUIRED CONFIG)

add_executable(hello_ippl hello_ippl.cpp)
target_link_libraries(hello_ippl PRIVATE IPPL::ippl)

Use the same compiler/MPI stack that was used to build IPPL:

cmake -S . -B build -G Ninja \
  -DCMAKE_CXX_COMPILER=mpicxx \
  -DCMAKE_PREFIX_PATH=/path/to/ippl/install
cmake --build build
mpiexec -n 2 build/hello_ippl

Do not mix a host compiler, a different MPI installation, or a different Kokkos installation with an existing IPPL build.

4.3 Common configure modes

cmake -S /path/to/ippl -B build-serial \
  -DCMAKE_BUILD_TYPE=RelWithDebInfo \
  -DCMAKE_CXX_STANDARD=20 \
  -DIPPL_PLATFORMS=SERIAL

cmake -S /path/to/ippl -B build-openmp \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_CXX_STANDARD=20 \
  -DIPPL_PLATFORMS=OPENMP \
  -DIPPL_ENABLE_FFT=OFF \
  -DIPPL_ENABLE_SOLVERS=OFF \
  -DIPPL_ENABLE_TESTS=ON

cmake -S /path/to/ippl -B build-cuda \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_CXX_STANDARD=20 \
  -DIPPL_PLATFORMS=CUDA \
  -DKokkos_ARCH_AMPERE80=ON \
  -DCMAKE_CUDA_ARCHITECTURES=80

4.4 Build options to document first

Option	Meaning
`IPPL_PLATFORMS`	Kokkos backends requested by IPPL, such as `SERIAL`, `OPENMP`, `CUDA`, or `HIP`.
`IPPL_ENABLE_FFT`	Enables FFT support and HeFFTe dependency logic.
`IPPL_ENABLE_SOLVERS`	Enables solver components that depend on FFT or linear solver infrastructure.
`IPPL_ENABLE_TESTS`	Enables integration tests and examples used as documentation.
`IPPL_ENABLE_UNIT_TESTS`	Enables GoogleTest-based unit tests.
`IPPL_USE_ALTERNATIVE_VARIANT`	Compatibility path for some CUDA/GCC combinations.