Underworld

a long term geodynamics simulation platform

Underworld Dependencies

Hardware Requirements

Underworld will work and be supported on any Linux-based operating system (PC and supercomputers) and Mac OS X (Power-PC and Intel macs). Underworld is not currently available for Windows. Underworld requires:

  • 300-500 MB for a compiled copy of Underworld.
  • 340 MB approx. for software dependencies.
  • at least 70 MB additional space for your own output data, 500 MB recommended for large problems.

Note for VPAC Computer Clusters: if you are using an account on a VPAC computer cluster such as EDDA, all of the required and visualisation applications have been installed for your use (excluding those for interactive visualisation which is not possible on the clusters) and are kept up-to-date by VPAC for you, and you can go back to the Releases page.

Note for Gentoo users: you can use Gentoo's emerge to install mpich, lapack, blas, subversion and libfame. Unfortunately petsc still must be installed manually. emerge will default install much of the software and may not produce what you desire from these packages; for instance mpich is set for ssh message passing by default instead of shmem. So make sure you know what emerge is doing if you have specific installation configurations.

Technical Knowledge

The instructions on this website assume only beginner's level familiarity with the Unix / Linux operating environment, including:

  • how to open a terminal window
  • how to navigate between directories using a terminal application
  • how to open, edit, save and close a file using an editor through a terminal application
  • which shell you are using e.g. bash, tcsh etc.

There are many beginners Unix / Linux guides available as textbooks and on the internet, including Unix Tutorial for Beginners.

Underworld Package Installs - go straight to binary package

All required software dependencies are installed for you together with the Underworld code when installing an Underworld release binary package (see downloads page).

Underworld Tarball or Repository Installs - software dependency installation

Underworld relies on a suite of software applications. Some of these are essential, while others facilitate particular visualisation capabilities, as outlined below.

Required Software

Underworld relies on the following software, all of which needs to be installed prior to installing Underworld from a source tarball or repository checkout (see previous section for binary installs). Click on the links for instructions on how to download and install each program. It is recommended that you install each program in the order listed. However, if you are going to install any of the Visualisation Software or Interactive Visualisation Software listed further below, install them before configuring PETSc. Note that these dependency instructions are intended as a guide only.

  1. C/C++ compiler - needed to compile several software dependencies and Underworld; on macs this can be installed from the developer tools - Xcode.
  2. MPI implementation - parallel MPI Message-passing library.
  3. Python - Python is required to compile PETSc and Mercurial, is used by the SCons build system in use by Underworld, is required by Mercurial which is the version control system currently being used by Underworld, the CREDO system testing and analysis framework, and several other optional components in Underworld.
  4. PETSc - a set of libraries including equation solvers and assembly routines.
  5. HDF5 - HDF5 is the default application used for checkpointing meshes and particles.
  6. SCons - the compilation software required to compile Underworld (comes packaged with versions of Underworld later than Underworld-1.2.0, so does not need to be installed separately).

In addition to the above, if you want to check out a version-controlled copy of Underworld from a repository, you will also need to install

  1. Mercurial - the version control system being used since Underworld-1.2.0.

Visualisation Software / Multimedia Output

The application gLucifer downloads with your copy of Underworld, and is required for visualisation of output images. gLucifer in turn requires some graphics libraries in order to run.

Image Libraries

The template InputFiles that come with Underworld default to output an image in png format and an mpeg file of these images. To export these image outputs, the following software is required. Click on the links for instructions on how to download and install each program:

  • libpng and / or libjpeg, libtiff or ppm - exports each image output to a png (default), jpeg, tiff and / or ppm file respectively (you only need to download the software which corresponds to the format(s) you require)
  • libavcodec or libfame - exports image outputs to an mpeg file (libavcodec recommended from Underworld 1.5.0)

Creating and drawing inside visualisation windows

For creation of visualisation window(s), you will need one of the following:

  • X11 - comes already installed by default on linux (Ubuntu/Debian: libx11-dev); comes as an option with development tools or optional installs with macs
  • Carbon - macs only, comes already installed (does not support interactive windows)
  • OSMesa - can be installed on most systems (Ubuntu/Debian: libosmesa6-dev), and is recommended for clusters; does not work with interactive simulations.
  • SDL - a cross-platform graphics output library; packages are available on linux (Ubuntu/Debian: libSDL1.2-dev), and on macs (using fink or MacPorts only)
  • GLUT - pre-installed on macs, packages available on linux (Ubuntu/Debian: freeglut3-dev).

To draw the image inside the created window(s), you will need one of:

  • OpenGL - should already come installed on macs; on linux additional header files may be required for your graphics card (if these are needed, Underworld will tell you it cannot find OpenGL when configuring Underworld). On Ubuntu/Debian based systems the required dev packages are libgl1-mesa-dev and libglu1-mesa-dev.
  • OSMesa - if you are installing on a local machine and would like to use interactive visualisation, which facilitates displaying of output images using gLucifer on the screen as they are created, do not use OSMesa. As Underworld selects OSMesa by default if found when configuring, you may have to disable it when running ./configure.py with the flag "--with-osmesa=0" (without the quotation marks). Conversely, If you are installing Underworld on a computer cluster, most of which will not be running the X11 daemon on compute nodes and therefore interactive visualisation will not be possible, it is recommended that you use OSMesa only.

All InputFiles can be run without interactive visualisation, in which case images are still created and can be opened manually. (See Underworld User Manual for further information on InputFiles, output and the Viewports directory).

Using the gLucifer Viewer

For creation of visualisation window(s), you will need to install SQLite. SQLite already come installed on some linux systems and with the developer tools on macs.

-- Wendy Mason - 29 June 2011
-- Owen Kaluza - 29 June 2011
-- Kathleen Humble - 06 April 2010
-- Patrick Sunter - 23 August 2010