How do I install on Ubuntu 14.04?

Oct 06, 2015

Installation instructions for linux Ubuntu 14.04

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.

1) Update ubuntu

Always a good idea to start with this.

2) Install dependencies via apt-get

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

sudo apt-get install swig
sudo apt-get install petsc-dev
sudo apt-get install hdf5-tools
sudo apt-get install libhdf5-dev
sudo apt-get install libhdf5-mpi-dev
sudo apt-get install freeglut3-dev
sudo apt-get install xorg-dev
sudo apt-get install python-dev
sudo apt-get install libpng-dev
sudo apt-get install python-virtualenv

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

virtualenv python-default
cd python-default/bin
source activate

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:

alias python-default='source /home/username/python-default/bin/activate'

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.

pip install scipy
pip install numpy
pip install ipython
pip install matplotlib

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.

sudo apt-get install libncurses5-dev
sudo apt-get install libfreetype6-dev

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.

sudo apt-get install libhdf5-mpi-dev

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

pip install Cython
pip install h5py
pip install mpi4py

6) Obtain u/w source

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

git clone https://github.com/underworldcode/underworld2 ~/underworld2-2015.10.01

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

cd libUnderworld/
./configure.py
cd libUnderworldPy/
./swigall.py
cd ../
./scons.py
cd ../

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

cd UserGuide/
source updatePyPath.sh
ipython notebook

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

import underworld as uw
help(uw.mesh)

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
/Users/username/+Codes/underworld2-gitology/underworld/mesh/__init__.py

PACKAGE CONTENTS
    _mesh
    _specialSets_Cartesian

The paths on your system to the various toolboxes will be spat out in the preamble text “found using ...

9) Troubleshooting

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.

PYTHONPATH=''

Then try run updatePyPath.sh again after

source ~/.bashrc