Installation

This section will guide you through installing the ARMI Framework on your machine.

Prerequisites

These instructions target users with some software development knowledge. In particular, we assume familiarity with Python, virtual environments, and Git.

You must have the following installed before proceeding:

Python version 3.9 or newer.

The right Python command

Python 2 and Python 3 often co-exist on the same system. Whether the python command refers to Python 2 or 3 depends on operating system and configuration. Under some circumstances python3 or pip3 will need to be used in place of python or pip to target the correct version. You can verify your version by running python -VV. You can also refer to the Python executable with a full path.

You also likely need the following for interacting with the source code repository:

Git

Preparing a Virtual Environment

While not technically required, we highly recommend installing ARMI into a virtual environment to assist in dependency management. In short, virtual environments are a mechanism by which a Python user can maintain separate sets of Python packages for various applications on the same machine. This prevents dependencies from various tools conflicting with one another. ARMI has a lot of requirements and may conflict with other libraries on your system unless you do this step.

Start a terminal and navigate to the directory you’d like to install ARMI into. To create a new virtual environment, use a command like:

$ python -m venv armi-venv

The result is a folder named armi-venv, which contains a minimal set of Python packages, and a set of scripts for activating and deactivating that environment. To activate the environment, invoke the appropriate script. On Windows:

$ armi-venv\Scripts\activate.bat

Or on Linux:

$ source armi-venv/bin/activate

Note

You’ll have to activate the venv every time you open a new command line. Many people set up scripts to activate this automatically.

If you will be running ARMI in parallel over MPI, you must also install the mpi4py Python library. On Linux, doing so will require some MPI development libraries (e.g. sudo apt install libopenmpi-dev).

Getting the code

Choose one of the following two installation methods depending on your needs.

Step 0: Update PIP

In order to use the commands below, you’re going to want to use a version of pip>=22.1. Two common ways of solving that are:

(armi-venv) $ pip install pip>=22.1

or, in most cases:

(armi-venv) $ pip install -U pip

Option 1: Install as a library

If you plan on running ARMI without viewing or modifying source code, you may install it with pip, which will automatically discover and install the dependencies. This is useful for quick evaluations or to use it as a dependency in another project:

(armi-venv) $ pip install https://github.com/terrapower/armi/archive/main.zip

Option 2: Install as a repository (for developers)

If you’d like to view or change the ARMI source code (common!), you need to clone the ARMI source and then install its dependencies. Clone the ARMI source code from the git repository with:

(armi-venv) $ git clone https://github.com/terrapower/armi

Tip

If you plan to contribute to ARMI (please do!), you may want to use SSH keys and use git clone git@github.com:terrapower/armi.git.

Now install ARMI with all its dependencies:

(armi-venv) $ cd armi
(armi-venv) $ pip install -e ".[test]"

Tip

If you don’t want to install ARMI into your venv, you will need to add the ARMI source location to your system’s PYTHONPATH environment variable so that Python will be able to find the code when you import it from other directories.

In Windows, click Start and type Edit Environmental Variable to adjust PYTHONPATH. In Linux, add export PYTHONPATH=/path/to/armi/source in a user profile script (like .bashrc).

Verifying installation

Check the installation status by running:

(armi-venv) $ armi

or, equivalently:

(armi-venv) $ python -m armi

If it worked, you should see the ARMI splash screen and no errors:

 ---------------------------------------------------
|             _      ____     __  __    ___         |
|            / \    |  _ \   |  \/  |  |_ _|        |
|           / _ \   | |_) |  | |\/| |   | |         |
|          / ___ \  |  _ <   | |  | |   | |         |
|         /_/   \_\ |_| \_\  |_|  |_|  |___|        |
|         Advanced  Reactor  Modeling Interface     |
 ---------------------------------------------------

If it works, congrats! So far so good.

Optional Setup

This subsection provides setup for optional items.

GUI input

To use the graphical core-map editor you will need to also install wxPython. This is not installed by default during armi installation because it can cause installation complexities on some platforms. In any case, all GUI dependencies can be installed by:

(armi-venv) $ pip install armi[grids]

GUI output

ARMI can write VTK and XDMF output files which can be viewed in tools such as ParaView and VisIT. Download and install those tools from their websites.