Easy Install using built-in CMake script

Install Development Tools

The following packages are required for OpenSn installation and development:

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

  2. gfortran (required by the BLAS component of PETSc)

  3. flex and bison (required by the PTSCOTCH component of PETSc)

  4. Python3 v3.9+ and pip (required by PETSc and OpenSn)

  5. Git version control system

  6. CMake v3.12+

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

  8. HDF5

  9. Doxygen (required for generating the OpenSn documentation)

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

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

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

Dependencies can be installed to /path/to/dependencies/directory with CMake as follows:

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

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

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.

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

To verify that the implementation is fully compatible with the current API of the code, run the test scripts:

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 build
make doc

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