Installation

OpenPhase-Academic v2.0 ships two equivalent build systems: a GNU Makefile (the default, used by every example and benchmark) and a CMake project (CMakeLists.txt, CMakePresets.json, minimum CMake 3.10) used on Windows with Intel oneAPI and available on Linux for integration with IDE tooling.

This page covers both paths, on Linux and on Windows. If you are on Windows and are not required to use Intel oneAPI, the Windows Subsystem for Linux (WSL) is the least-friction option.

Prerequisites

Required

Requirement	Version	Notes
C++ compiler with C++17 support	GCC ≥ 9.0, Clang, Intel DPC++ / icx	Intel icpc is not supported; use icx.
FFTW3	3.x	Replaced by MKL FFTW on Windows; see the Windows path below.
GNU Make or CMake ≥ 3.10	—	Choose one.
Git	any recent	Used by the CMake build to stamp the commit SHA into include/BuildInfo.h.

Optional

Optional	Purpose
MPI implementation (OpenMPI, MPICH, Intel MPI, MS-MPI)	Distributed-memory parallelism. Enable with SETTINGS=mpi-parallel or CMake -DENABLE_MPI=ON.
FFTW3 MPI (libfftw3-mpi-dev)	Required if MPI is enabled and you are not on Windows.
Cantera	Reactive-flow chemistry. Export CANTERA_PATH; the CMake build picks it up automatically.
Doxygen	Generate the code-level reference into ./documentation.

Hardware

• Multi-core CPU — OpenMP scales with thread count.
• ≥ 8 GB RAM for small 2D / 3D grids; 16 GB or more for larger 3D studies.
• ≥ 10 GB free disk.

Linux

Install the toolchain (Ubuntu / Debian)

sudo apt update
sudo apt install build-essential fftw-dev libfftw3-3 libfftw3-dev

Verify:

g++ --version      # need 9.0.0 or later

For MPI add:

sudo apt install openmpi-bin libopenmpi-dev libfftw3-mpi-dev

For CMake (only if you will use the CMake build):

sudo apt install cmake ninja-build

Clone and build with Make

git clone https://github.com/ICAMS/OpenPhase.git
cd OpenPhase
make

This compiles the library into ./lib and prints Compilation done on success. To compile the example simulations and the benchmark suite:

make examples
make benchmarks

Makefile build settings

Additional compile-time options are passed through SETTINGS:

make SETTINGS="mpi-parallel debug"

SETTINGS value	Effect
(none)	Default: OpenMP on, release optimisation.
serial	Disable OpenMP.
mpi-parallel	Enable MPI. Requires libfftw3-mpi-dev on Linux.
debug	Compile with debug symbols and the DEBUG preprocessor flag.
silent	Suppress most console output from the library.

OpenMP is on by default; use SETTINGS=serial to disable it.

Changing the compiler

make CXX=clang++
make CXX=icx

Clone and build with CMake

git clone https://github.com/ICAMS/OpenPhase.git
cd OpenPhase
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build . -j

To use Clang:

cmake -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_C_COMPILER=clang \
      -DCMAKE_BUILD_TYPE=Release ..
cmake --build . -j

CMake options

Every CMake option is declared in CMakeLists.txt. Pass any of them to cmake .. as -D<OPTION>=<value>.

Option	Default	Effect
CMAKE_BUILD_TYPE	Debug	Use Release for optimised builds.
ENABLE_OPENMP	ON	OpenMP parallelism.
ENABLE_MPI	ON	MPI parallelism (requires an MPI library; FFTW3-MPI on Linux).
ENABLE_BENCHMARKS	ON	Build benchmarks/*.
ENABLE_EXAMPLES	ON	Build examples/*.
ENABLE_DYNAMIC_LIBS	ON	Build a shared library; set to OFF for static.
ENABLE_DYNAMIC_LINKING	ON	Link FFTW / OpenMP dynamically.
ENABLE_ACADEMIC	ON	Academic-edition defines (-DACADEMIC).
ENABLE_SENTINEL	OFF	Copy protection (commercial editions only).

Note: do not hard-code the compiler in CMakeLists.txt. Use -DCMAKE_CXX_COMPILER=... on the CMake command line or set the CC and CXX environment variables.

CMake only needs to be re-run when CMakeLists.txt itself changes. Incremental rebuilds use cmake --build ..

Testing, installing, packaging

From inside the CMake build/ directory:

make test               # run the benchmark-based test suite
sudo make install       # default prefix /usr/local
make package            # CPack binary package
make package_source     # source tarball

Override the prefix for a local install:

make DESTDIR=/home/<user> install

Add /usr/local/lib (or your custom prefix) to LD_LIBRARY_PATH so executables linked against the shared library can find it at runtime.

Windows — Intel oneAPI + CMake

This is the first-class Windows path. It uses Intel oneAPI (with MKL providing the FFTW interface) and Ninja.

Prerequisites

• Intel oneAPI Base Toolkit — supplies icx, icpx, and MKL.
• CMake ≥ 3.10.
• Ninja.

After installing, confirm both are on PATH:

cmake --version
ninja --version

Build

git clone https://github.com/ICAMS/OpenPhase.git
cd OpenPhase

# Enter the oneAPI command environment (adjust path if needed): {#enter-the-oneapi-command-environment-adjust-path-if-needed}
cmd.exe "/K" '"C:\Program Files (x86)\Intel\oneAPI\setvars.bat" && powershell'

# Use the provided preset — equivalent to a Release config with MKL: {#use-the-provided-preset-equivalent-to-a-release-config-with-mkl}
cmake --preset intel-release
cmake --build --preset intel-release

Other presets (intel-debug) are declared in CMakePresets.json.

To suppress warnings for a clean build log:

cmake -G Ninja -DCMAKE_CXX_COMPILER=icx -DCMAKE_CXX_FLAGS="-w" ..
cmake --build .

The resulting library, examples, and benchmarks land under build/<preset>/. Example executables have the OpenPhase DLL copied next to them automatically by the CMake build.

Windows — WSL

If Intel oneAPI is not required, run the library in WSL and use the Linux Makefile or CMake path above.

# From an elevated PowerShell: {#from-an-elevated-powershell}
wsl --install

Reboot, create your Linux user, then inside the WSL shell follow the Linux → Install the toolchain and subsequent steps.

Verify the installation

Whichever build system you used, run one of the shipped examples:

cd examples/NormalGG
./NormalGG                 # Make build
# or, for a CMake build: {#or-for-a-cmake-build}
./build/Release/examples/NormalGG/NormalGG

NormalGG is a ready-to-run grain-growth simulation: it reads ProjectInput.opi from the working directory, writes VTK output into VTK/, and prints the interface energy density every 100 steps. If you see console output and VTK files appearing, the library is working.

Troubleshooting

g++: command not found

sudo apt install build-essential

fftw3.h: No such file or directory

sudo apt install libfftw3-dev

On Windows with Intel oneAPI this header is provided by MKL at <oneapi-root>/include/fftw; the CMake build finds it automatically through find_package(MKL REQUIRED).

Linker errors mentioning fftw3_mpi or MPI_Init

You enabled MPI (SETTINGS=mpi-parallel or -DENABLE_MPI=ON) but the MPI-aware FFTW3 and an MPI library are not installed:

sudo apt install openmpi-bin libopenmpi-dev libfftw3-mpi-dev

CMake cannot find FFTW3 on Linux

export CMAKE_PREFIX_PATH=/usr/lib/x86_64-linux-gnu:$CMAKE_PREFIX_PATH

Or pass -DFFTW_INCLUDE_DIR=... / -DFFTW_LIBRARY=... directly to cmake.

Static linking of OpenMP and Sentinel is not supported

Combine -DENABLE_DYNAMIC_LINKING=ON with any Sentinel-protected build, or disable Sentinel (-DENABLE_SENTINEL=OFF).

Generating code-level documentation

doxygen                 # from the OpenPhase root
# Output: ./documentation/html/index.html {#output-documentationhtmlindexhtml}

The documentation/UserManual/UserManual.pdf is also shipped in the source distribution.

Next steps

• Your First Simulation — walk through the minimal NormalGG-style setup.
• Project Structure — understand where the source, examples, and outputs live.
• Modules — reference for each module and its .opi token set.