2. Easy Install on Linux Machines

The following instructions were tested on Ubuntu 22.04.4 LTS. Other Linux distributions might require some minor tweaking.

Some portions of these instructions require the use of sudo. If you do not have administrative privileges, have your system administrator assist you with these steps.

Note that these instructions assume you are using the bash shell and may differ slightly for other shells.

2.1. Step 1 - Install Development Tools

The following packages are required for OpenSn installation and development:

A recent version of clang++/g++ that supports C++17
gfortran (required by the BLAS component of PETSc)
flex and bison (required by the PTSCOTCH component of PETSc)
Python 3 v3.9+ and pip (required by PETSc and OpenSn)
ncurses v5 (required by Lua)
Git version control system
CMake v3.12+
MPI (OpenMPI, MPICH, and MVAPICH have been tested)
Doxygen and Sphinx (required for generating the OpenSn documentation)
curl (required to download and install the OpenSn third-party dependencies)

Most of these packages can be installed using the package manager available with your Linux distribution (e.g., apt, yum, etc.). For example, on Ubuntu, you can use the following command to install all of these packages:

$ sudo apt install build-essential gfortran python3 \
git cmake libopenmpi-dev flex bison \
libncurses5-dev python3-pip doxygen sphinx curl

To ensure that all third-party packages use the required MPI compiler wrappers, the following environment variables must be set:

    $ export CC=mpicc
    $ export CXX=mpicxx
    $ export FC=mpifort

2.2. Step 2 - 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

2.3. Step 3 - Install Third-Party Libraries

Important: We recommend creating a separate directory for building the OpenSn dependencies.

Assuming you created a directory named dependencies to be used for building the required third-party packages, the following command automates the install and build process:

    $ cd opensn
    $ python3 tools/configure_dependencies.py -d ../path/to/dependencies/directory

2.4. Step 4 - Configure Environment

Before compiling OpenSn, you must add the location of the third-party libraries to your CMAKE_PREFIX_PATH environment variable. This can be accomplished with the following command:

$ export CMAKE_PREFIX_PATH=/path/to/dependencies${CMAKE_PREFIX_PATH:+:${CMAKE_PREFIX_PATH}}`

Important: It may be a good idea to add the CMAKE_PREFIX_PATH variable to your .bashrc file so that you don’t need to specify the path every time you need to re-run cmake.

2.5. Step 5 - Build OpenSn

To build OpenSn, create a build directory in the top-level OpenSn directory and run cmake to generate the build files and make to compile OpenSn:

    $ mkdir build
    $ cd build
    $ cmake ..
    $ make -j<N>

To configure OpenSn for building the documentation, in addition to the OpenSn application, add the -DOPENSN_WITH_DOCS option to cmake:

    $ mkdir build
    $ cd build
    $ cmake -DOPENSN_WITH_DOCS=ON ..
    $ make -j<N>

For more information on building the documentation, see Step 7 below.

2.6. Step 6 - Run Regression Tests

To run the regression tests, simply run make test from the build directory. This will run all of the regression tests in the opensn/test directory.

2.7. Step 7 - Build the OpenSn Documentation

If you configured the OpenSn build environment with support for building the documentation (see Step 5), these instructions will help you install the necessary tools and build the documentation.

To generate the documentation from your local working copy of OpenSn, you need to use pip to install the required Python packages:

pip install breathe myst-parser sphinx_rtd_theme

Then, from your build directory, you can run the command make doc to generate the documentation:

cd build
make doc

Once the build process has completed, you can view the generated documentation by opening opensn/build/doc/index.html in your favorite web browser.