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.
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.
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.
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
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.
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 /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 ... ”
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
Then try run
updatePyPath.sh again after