This is a quick step-by-step guide to installing a fresh copy of underworld on the ubuntu 14.04 flavour of linux. We will assume that python has already been installed (as is default) and that you have permissions to use apt-get as well as pip to install our python dependencies.

Everything requires sudo access to the terminal.

### 2) Install dependencies via apt-get

Open a terminal and make sure that you have sudo permissions before installing the following.

Note that some of these have many dependencies of their own so each step can take several minutes.

You may also need to install other packages when pip installing the python dependencies below. This depends on the configuration of your system.

### 3) Setting up virtual python environments

If you are using virtual python environments (recommended but not required) then start up your virtual environment before using pip install. If you are not using a virtual python environment then proceed to the next step.

To set up a virtual environment called python-default use the following commands

You can then add an alias your .bashrc file to automatically run this activation each time you wish to being a python session using underworld. An example of the alias is:

### 4) Install python dependencies via pip

If you use virtual environments then make sure the it is active. In the above example you will have (python-default) at the begining of the shell.

Now use pip (comes with python) to install more python packages required by underworld.

Watch carefully at the end to make sure that each installed correctly.

### 5) Potential issues with python dependencies

Some issues have been encountered during the pip install process, specifically involving matplotlib. The following additional packages may be needed when to successfully install matplotlib.

After these (and any other missing packages) are installed, retry the failed pip install commands.

An additional issue has been encountered regarding parallel version of the HDF5 library. This can be fixed by making sure the following package is installed.

Depending on the configuration of your system you may also need to install or update the following.

### 6) Obtain u/w source

The installation path for underworld is not especially important but you can specify it explicitly at this stage:

The website github repository is found at https://github.com/underworldcode/underworldcode.github.io.git (authorisation required)

### 7) Configure & Build

Go into your underworld directory (e.g. ~/underworld2) and type the following commands

Assuming everything compiled without error, you should now be back in the original underworld2 directory and ready to run underworld. If something has gone wrong, check the error message and make sure that the appropriate packages have been installed.

### 8) Running

From the main underworld directory (e.g. ~/underworld2) start your virtual python environment (if using) and type the following commands

To quickly test that underworld is working correctly, open a new notebook and in the first cell type:

You should see in response:

Toolbox "StgDomain" found using ...
Toolbox "StgFEM" found using ...
Toolbox "PICellerator" found using ...
Toolbox "Underworld" found using ...
Toolbox "gLucifer" found using ...
Toolbox "Solvers" found using ...

Help on package underworld.mesh in underworld:

NAME
underworld.mesh - Implementation relating to meshing.

FILE

The paths on your system to the various toolboxes will be spat out in the preamble text “found using ...
Sometimes running the updatePyPath.sh script fails to find a python path variable to add to. This can be fixed by adding the following line to your .bashrc file.
Then try run updatePyPath.sh again after