OpenSn Installation

Install Development Tools

Before installing OpenSn, you must have the following packages installed on your system:

1. A recent version of clang++/g++ that supports C++20

2. Python 3.9+ with pybind11 and pip

3. Git version control system

4. CMake v3.29+

5. MPI (OpenMPI, MPICH, and MVAPICH have been tested)

6. flex (required by the PTSCOTCH component of PETSc)

7. Pandoc and Doxygen (only if you plan to build documentation)

You can install these packages using your system package manager:

Linux (Ubuntu)

sudo apt install build-essential python3-dev python3-pip \
    git cmake libopenmpi-dev flex doxygen pandoc
export NPROC=$(nproc)

macOS

brew install gcc python git cmake open-mpi flex doxygen pandoc
export NPROC=$(sysctl -n hw.ncpu)

The following additional packages will be installed by the OpenSn dependency build (if not found on your system):

1. PETSc 3.17.0+

2. Boost 1.86+

3. HDF5 1.14+

4. VTK 9.3.0+

5. Caliper 2.11+

OpenSn calls LAPACK through PETSc and links the BLAS/LAPACK libraries that PETSc was built with, which CMake reads from BLASLAPACK_LIB in PETSc’s lib/petsc/conf/petscvariables. The configure output reports them on the BLAS/LAPACK: line. If PETSc does not record them, CMake searches for a system LAPACK with the integer width of PETSc’s BLAS (32-bit, or 64-bit when PETSc uses 64-bit BLAS indices). In that case, set BLA_VENDOR or LAPACK_LIBRARIES to the LAPACK that PETSc uses.

Install with Docker

OpenSn provides a Dockerfile under distribution/docker for building and running OpenSn in an Ubuntu-based container.

See distribution/docker/README.md for build and run instructions.

Install with Spack

OpenSn provides a local Spack package repository under distribution/spack. This can be used to install OpenSn and its dependency stack with Spack.

See distribution/spack/README.md for install commands, supported variants, test behavior, executable lookup, and development workflows.

Virtual environments (recommended)

Using a virtual environment keeps Python dependencies isolated from your system packages and makes it easier to cleanly uninstall or upgrade later.

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip

The environment must be activated in each new shell session before running pip or OpenSn’s Python tools.

source .venv/bin/activate
python -m pip install pybind11

To leave the environment, run:

deactivate

Clone OpenSn

Important

If you want to contribute to OpenSn, it is strongly recommended that you first fork the OpenSn repository then clone your fork.

To clone the OpenSn repository:

git clone https://github.com/Open-Sn/opensn.git

To clone your fork of OpenSn:

git clone https://github.com/<username>/opensn.git

Install dependencies

You can install all required dependencies for OpenSn into a dedicated directory using CMake:

mkdir build_deps && cd build_deps
cmake -DCMAKE_INSTALL_PREFIX=/path/to/dependencies/directory \
      /path/to/opensn/tools/dependencies
make -j
cd ..
rm -rf build_deps

During this step, CMake automatically searches for compatible system installations of the required packages. Any missing dependencies will be downloaded, built, and installed into the specified directory.

When the process completes, a helper script named set_opensn_env.sh is generated in the installation directory:

/path/to/dependencies/directory/bin/set_opensn_env.sh

This script updates your environment so that future CMake builds can locate the installed libraries and headers. To make these settings persistent, add the following line to your shell’s startup file (for example, ~/.bashrc or ~/.zshrc):

source /path/to/dependencies/directory/bin/set_opensn_env.sh

Sourcing this script ensures that OpenSn uses the correct versions of all required dependencies. This setup is recommended for both end users and developers working on the OpenSn code base.

Configure and build OpenSn

OpenSn provides a Python interface. It is available in two formats: a console application opensn and a Python module pyopensn.

Classes and functions in the Python interface are detailed in Python API.

Attention

The console and the module are not compatible with each other. Attempting to import the module within the console will result in an import error. Users should select one approach and maintain consistent coding style throughout.

Console application

To compile the console application:

mkdir build
cd build
cmake ..
make -j$NPROC

Note

CMake builds also compile the unit-test executable test/opensn-unit, downloading GoogleTest if it is not found on the system. To skip the tests in a production build, configure with -DOPENSN_BUILD_TESTING=OFF. If that option is not set, it follows the standard CMake BUILD_TESTING variable when one is provided. The module build performed by pip install . always disables the tests.

Note

On Linux, libopensn is linked with -z defs, so the link fails if a symbol it uses is not provided by one of the libraries it links, as on macOS. With Clang sanitizers, link the shared sanitizer runtime with -shared-libsan -frtlib-add-rpath, as the clang+debug+sanitizer preset does, so that libopensn links it and executables find it at run time. When the sanitizer runtime is static, and linked only into executables, CMake skips this check.

Note

On Linux, importing a pyopensn module built with AddressSanitizer from an ordinary Python interpreter aborts with “ASan runtime does not come first in initial library list”. Preload the runtime of the Clang that built the module. LeakSanitizer then reports the interpreter’s own allocations at exit, so disable leak detection:

LD_PRELOAD=$(clang -print-file-name=libclang_rt.asan.so) \
  ASAN_OPTIONS=detect_leaks=0 python3 input.py

Danger

In the console application, all classes and functions are implicitly imported into the __main__ module at startup. Therefore, omit submodule prefixes when referring to class or function names. Additionally, avoid redefining any OpenSn class or function names to prevent naming conflicts.

GPU builds

GPU sweeps need one GPU backend, chosen at configure time with -DOPENSN_WITH_CUDA=ON, -DOPENSN_WITH_HIP=ON, or -DOPENSN_WITH_SYCL=ON, and the device architecture, for example -DCMAKE_CUDA_ARCHITECTURES=90 or -DCMAKE_HIP_ARCHITECTURES=gfx942. -DOPENSN_USE_GPU_AWARE_MPI=ON passes device buffers directly to MPI. CMake then checks that the MPI library supports the backend, and on Cray MPICH it links the needed GPU transport library. See Running Problems for the run-time settings.

Module

To compile the module and install in the Python site-packages path:

pip install .

For developers, it is recommended to use the following command to install the additional packages required for running regression tests:

pip install .[dev]

Tip

Unlike the console, the Python interface is fully compatible with mpi4py. Both OpenSn and mpi4py share the same MPI communicator. Therefore, the Python module can be used in scripts that incorporate other tasks using mpi4py.

Run regression tests

Run the regression tests to verify your installation:

cd /path/to/opensn
test/run_tests -d test/python -j$NPROC -v 1 -w 3

Attention

Regression tests require both the console and the module. This can be achieved with:

cmake -DOPENSN_WITH_PYTHON_MODULE=ON ..

Build documentation

Install the required Python packages to the virtual environment using pip:

cd doc
pip install -r requirements.txt

Important

Compiling documentation requires the Python module of OpenSn.

Then, from your build directory, generate the documentation with:

cd doc
make html

Once the build process is complete, you can view the generated documentation by opening doc/build/html/index.html in your preferred web browser.