2. Installation and Configuration

2.2. Obtaining the Source

All OpenMOC 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/OpenMOC.git

2.3. Building From Source

2.3.1. Standard Build Configuration

To compile and install the code in a user local directory (recommended), simply run the following from the console:

python setup.py install --user

Warning

The --user flag should be used verbatim and should NOT be replaced with your username.

To compile and install the code in the directory of all Python packages accessible to all users of your machine (not recommended), run the following command:

python setup.py install

The code will now be accessible as a Python module from anywhere on your system. The main OpenMOC Python package can be imported into any Python script as follows:

import openmoc

2.3.2. Custom Build Configuration

OpenMOC provides a number of user options to customize what and how OpenMOC source is compiled and built on your system. OpenMOC makes use of Python’s distutils build configuration management module.

To view a list of all of build commands supported by Python distutils, type the following in the console:

python setup.py --help-commands

To install OpenMOC, we typically recommend using the install command which builds and installs the code alongside other commonly referenced Python packagaes. The install command includes its own set of options, some of which are defined by OpenMOC and some of which are defined by distutils. To view a list of these options, type the following in the console:

python setup.py install --help

2.3.3. Build Configuration Options

This section section will provides an overview of the most useful and relevant build options for OpenMOC developers.

--user

Installs OpenMOC in a user local directory (ie, /home/username/.local/lib/pythonX.X/site-packages) where it will only be accessible to your username. Installation without this option will instead install OpenMOC in the main Python directory accessible to all users of your machine (ie, /usr/lib/pythonX.X/site-packages/). This option is highly recommended for developers as it will prevent your Python packages from being polluted with code that has not yet been validated.

--prefix=<path to install OpenMOC>

Installs OpenMOC to an explicitly defined directory. This options is generally not useful unless your directory is included in your PYTHONPATH such that you can import openmoc into your Python scripts.

--cc=<gcc,icpc,clang,bgxlc>

Sets the C++ compiler for the main openmoc module. Presently, GNU’s gcc, Intel’s icpc, Apple’s clang and IBM’s bgxlc are all configured if the path to the binary is pointed to by by the PATH environment variable. The default setting is the gcc compiler.

--fp=<single,double>

Sets the floating point precision level for the main openmoc module. This sets the FP_PRECISION macro in the source code by setting it as an environment variable at compile time. The default setting is single.

--with-cuda

Compiles the openmoc.cuda module using the nvcc compiler. This module contains GPUSolver class with MOC routines for execution on NVIDIA GPUs. The default build configuration does not include the openmoc.cuda module.

--debug-mode

Compiles with debugging symbols and information by including the -g compile flag.

--sanitizer-mode

Compiles with ASan, an address sanitizer developped by Google that detects memory corruption bugs. Compatible with GCC and Clang.

--profile-mode

Compiles with profiling information by including the -p compile flag.

--with-ccache

Compiles using ccache which uses a cache to speedup compilation of unchanged source files with the binaries from previous compilations. This flag is only relevant for developers needing to frequently recompile the source code. The ccache p]rogram must be installed for this flag to work. The following console command will install ccache on Ubuntu:

sudo apt-get install ccache

2.4. Installing with Docker

A Dockerfile that installs OpenMOC and its dependences is provided. A container may be permanently hosted in the future.

# Build image
docker build -t <container name>

# List images
docker images

# Execute the image
docker run <container name>

# Run a shell inside the container
docker-compose run <container name> /bin/bash
# or
docker exec -it <container name> /bin/bash

Note

Running OpenMOC from Docker will be significantly slower than the regular build