2. Installation and Configuration

2.1. Installing on Linux/Mac with conda-forge

Conda is an open source package management system and environment management system for installing multiple versions of software packages and their dependencies and switching easily between them. conda-forge is a community-led conda channel of installable packages. For instructions on installing conda, please consult their documentation.

Once you have conda installed on your system, add the conda-forge channel to your configuration with:

conda config --add channels conda-forge

Once the conda-forge channel has been enabled, OpenMC can then be installed with:

conda install openmc

It is possible to list all of the versions of OpenMC available on your platform with:

conda search openmc --channel conda-forge

2.2. Installing on Ubuntu with PPA

For users with Ubuntu 15.04 or later, a binary package for OpenMC is available through a Personal Package Archive (PPA) and can be installed through the APT package manager. First, add the following PPA to the repository sources:

sudo apt-add-repository ppa:paulromano/staging

Next, resynchronize the package index files:

sudo apt update

Now OpenMC should be recognized within the repository and can be installed:

sudo apt install openmc

Binary packages from this PPA may exist for earlier versions of Ubuntu, but they are no longer supported.

2.3. Building from Source

2.3.1. Prerequisites

Required

  • A Fortran compiler such as gfortran

    In order to compile OpenMC, you will need to have a Fortran compiler installed on your machine. Since a number of Fortran 2003/2008 features are used in the code, it is recommended that you use the latest version of whatever compiler you choose. For gfortran, it is necessary to use version 4.8.0 or above.

    If you are using Debian or a Debian derivative such as Ubuntu, you can install the gfortran compiler using the following command:

    sudo apt install gfortran
    
  • A C/C++ compiler such as gcc

    OpenMC includes various source files written in C and C++, respectively. These source files have been tested to work with a wide variety of compilers. If you are using a Debian-based distribution, you can install the g++ compiler using the following command:

    sudo apt install g++
    
  • CMake cross-platform build system

    The compiling and linking of source files is handled by CMake in a platform-independent manner. If you are using Debian or a Debian derivative such as Ubuntu, you can install CMake using the following command:

    sudo apt install cmake
    
  • HDF5 Library for portable binary output format

    OpenMC uses HDF5 for many input/output files. As such, you will need to have HDF5 installed on your computer. The installed version will need to have been compiled with the same compiler you intend to compile OpenMC with. If compiling with gcc from the APT repositories, users of Debian derivatives can install HDF5 and/or parallel HDF5 through the package manager:

    sudo apt install libhdf5-dev
    

    Parallel versions of the HDF5 library called libhdf5-mpich-dev and libhdf5-openmpi-dev exist which are built against MPICH and OpenMPI, respectively. To link against a parallel HDF5 library, make sure to set the HDF5_PREFER_PARALLEL CMake option, e.g.:

    FC=mpifort.mpich cmake -DHDF5_PREFER_PARALLEL=on ..
    

    Note that the exact package names may vary depending on your particular distribution and version.

    If you are using building HDF5 from source in conjunction with MPI, we recommend that your HDF5 installation be built with parallel I/O features. An example of configuring HDF5 is listed below:

    FC=mpifort ./configure --enable-fortran --enable-parallel
    

    You may omit --enable-parallel if you want to compile HDF5 in serial.

    Important

    If you are building HDF5 version 1.8.x or earlier, you must include --enable-fortran2003 when configuring HDF5 or else OpenMC will not be able to compile.

Optional

  • An MPI implementation for distributed-memory parallel runs

    To compile with support for parallel runs on a distributed-memory architecture, you will need to have a valid implementation of MPI installed on your machine. The code has been tested and is known to work with the latest versions of both OpenMPI and MPICH. OpenMPI and/or MPICH can be installed on Debian derivatives with:

    sudo apt install mpich libmpich-dev
    sudo apt install openmpi-bin libopenmpi-dev
    
  • git version control software for obtaining source code

2.3.2. Obtaining the Source

All OpenMC source code is hosted on GitHub. You can download the source code directly from GitHub or, if you have the git version control software installed on your computer, you can use git to obtain the source code. The latter method has the benefit that it is easy to receive updates directly from the GitHub repository. GitHub has a good set of instructions for how to set up git to work with GitHub since this involves setting up ssh keys. With git installed and setup, the following command will download the full source code from the GitHub repository:

git clone https://github.com/mit-crpg/openmc.git

By default, the cloned repository will be set to the development branch. To switch to the source of the latest stable release, run the following commands:

cd openmc
git checkout master

2.3.3. Build Configuration

Compiling OpenMC with CMake is carried out in two steps. First, cmake is run to determine the compiler, whether optional packages (MPI, HDF5) are available, to generate a list of dependencies between source files so that they may be compiled in the correct order, and to generate a normal Makefile. The Makefile is then used by make to actually carry out the compile and linking commands. A typical out-of-source build would thus look something like the following

mkdir build && cd build
cmake ..
make

Note that first a build directory is created as a subdirectory of the source directory. The Makefile in the top-level directory will automatically perform an out-of-source build with default options.

2.3.3.1. CMakeLists.txt Options

The following options are available in the CMakeLists.txt file:

debug
Enables debugging when compiling. The flags added are dependent on which compiler is used.
profile
Enables profiling using the GNU profiler, gprof.
optimize
Enables high-optimization using compiler-dependent flags. For gfortran and Intel Fortran, this compiles with -O3.
openmp
Enables shared-memory parallelism using the OpenMP API. The Fortran compiler being used must support OpenMP. (Default: on)
coverage
Compile and link code instrumented for coverage analysis. This is typically used in conjunction with gcov.
maxcoord
Maximum number of nested coordinate levels in geometry. Defaults to 10.

To set any of these options (e.g. turning on debug mode), the following form should be used:

cmake -Ddebug=on /path/to/openmc

2.3.3.2. Compiling with MPI

To compile with MPI, set the FC and CC environment variables to the path to the MPI Fortran and C wrappers, respectively. For example, in a bash shell:

export FC=mpif90
export CC=mpicc
cmake /path/to/openmc

Note that in many shells, environment variables can be set for a single command, i.e.

FC=mpif90 CC=mpicc cmake /path/to/openmc

2.3.3.3. Selecting HDF5 Installation

CMakeLists.txt searches for the h5fc or h5pfc HDF5 Fortran wrapper on your PATH environment variable and subsequently uses it to determine library locations and compile flags. If you have multiple installations of HDF5 or one that does not appear on your PATH, you can set the HDF5_ROOT environment variable to the root directory of the HDF5 installation, e.g.

export HDF5_ROOT=/opt/hdf5/1.8.15
cmake /path/to/openmc

This will cause CMake to search first in /opt/hdf5/1.8.15/bin for h5fc / h5pfc before it searches elsewhere. As noted above, an environment variable can typically be set for a single command, i.e.

HDF5_ROOT=/opt/hdf5/1.8.15 cmake /path/to/openmc

2.3.4. Compiling on Linux and Mac OS X

To compile OpenMC on Linux or Max OS X, run the following commands from within the root directory of the source code:

mkdir build && cd build
cmake ..
make
make install

This will build an executable named openmc and install it (by default in /usr/local/bin). If you do not have administrative privileges, you can install OpenMC locally by specifying an install prefix when running cmake:

cmake -DCMAKE_INSTALL_PREFIX=$HOME/.local ..

The CMAKE_INSTALL_PREFIX variable can be changed to any path for which you have write-access.

2.3.5. Compiling on Windows 10

Recent versions of Windows 10 include a subsystem for Linux that allows one to run Bash within Ubuntu running in Windows. First, follow the installation guide here to get Bash on Ubuntu on Windows setup. Once you are within bash, obtain the necessary prerequisites via apt. Finally, follow the instructions for compiling on linux.

2.3.6. Compiling for the Intel Xeon Phi

For the second generation Knights Landing architecture, nothing special is required to compile OpenMC. You may wish to experiment with compiler flags that control generation of vector instructions to see what configuration gives optimal performance for your target problem.

For the first generation Knights Corner architecture, it is necessary to cross-compile OpenMC. If you are using the Intel Fortran compiler, it is necessary to specify that all objects be compiled with the -mmic flag as follows:

mkdir build && cd build
FC=ifort CC=icc FFLAGS=-mmic cmake -Dopenmp=on ..
make

Note that unless an HDF5 build for the Intel Xeon Phi (Knights Corner) is already on your target machine, you will need to cross-compile HDF5 for the Xeon Phi. An example script to build zlib and HDF5 provides several necessary workarounds.

2.3.7. Testing Build

To run the test suite, you will first need to download a pre-generated cross section library along with windowed multipole data. Please refer to our OpenMC Test Suite documentation for further details.

2.4. Python Prerequisites

OpenMC’s Python API works with either Python 2.7 or Python 3.2+. In addition to Python itself, the API relies on a number of third-party packages. All prerequisites can be installed using conda (recommended), pip, or through the package manager in most Linux distributions.

Required

six
The Python API works with both Python 2.7+ and 3.2+. To do so, the six compatibility library is used.
NumPy
NumPy is used extensively within the Python API for its powerful N-dimensional array.
SciPy
SciPy’s special functions, sparse matrices, and spatial data structures are used for several optional features in the API.
pandas
Pandas is used to generate tally DataFrames as demonstrated in Pandas Dataframes example notebook.
h5py
h5py provides Python bindings to the HDF5 library. Since OpenMC outputs various HDF5 files, h5py is needed to provide access to data within these files from Python.
Matplotlib
Matplotlib is used to providing plotting functionality in the API like the Universe.plot() method and the openmc.plot_xs() function.
uncertainties
Uncertainties are used for decay data in the openmc.data module.
lxml
lxml is used for the openmc-validate-xml script and various other parts of the Python API.

Optional

Cython
Cython is used for resonance reconstruction for ENDF data converted to openmc.data.IncidentNeutron.
vtk
The Python VTK bindings are needed to convert voxel and track files to VTK format.
silomesh
The silomesh package is needed to convert voxel and track files to SILO format.
pytest
The pytest framework is used for unit testing the Python API.

2.5. Configuring Input Validation with GNU Emacs nXML mode

The GNU Emacs text editor has a built-in mode that extends functionality for editing XML files. One of the features in nXML mode is the ability to perform real-time validation of XML files against a RELAX NG schema. The OpenMC source contains RELAX NG schemas for each type of user input file. In order for nXML mode to know about these schemas, you need to tell emacs where to find a “locating files” description. Adding the following lines to your ~/.emacs file will enable real-time validation of XML input files:

(require 'rng-loc)
(add-to-list 'rng-schema-locating-files "~/openmc/schemas.xml")

Make sure to replace the last string on the second line with the path to the schemas.xml file in your own OpenMC source directory.