Contents

Introduction
Installation
1. Underworld
2. UnderworldGUI
Getting Started
1. A Basic Overview
2. Using the UnderworldGUI: One Example
Changing Settings
1. Debugging
2. Visual themes
Model Libraries
Troubleshooting
References

1. Introduction

1.1. What "Underworld" does

Underworld is a geodynamics modeling code based on StGermain, StgFEM and PICellerator. Its applications are formed out of building on top of StgFEM/PICellerator extension modules which are assembled for solving a particular task. Underworld forms the geodynamics knowledge of the Snark project [1].

Paraphrasing this (perhaps somewhat carelessly), the Underworld software allows the scientist to simulate geological/geodynamic events, and observe a variety of outcomes based on parameters that the scientist him/herself specifies. Furthermore, the simulation experiments carried out by the scientist will be most powerful when employed as part of an iterative process. One example of the software's usage is to model a cross-section of the Earth's crust, inserting stress points, and witnessing the effects of the inevitable factors: time and the shifting of the layers. By iterating simulation after simulation, the scientist will be able to narrow down ranges of parameter values until they're able to recreate the phenomenon they are expecting within a certain acceptable level of inaccuracy.

1.2. What "UnderworldGUI" does

The UnderworldGUI simplifies the process of creating input models for Underworld-driven simulations, submitting these models to the Underworld software, and retrieving the simulation results upon completion of the simulation. To facilitate scientific collaboration and dialogue, and to assist individual users in managing their work, the UnderworldGUI also stores each model that is submitted to the Underworld as an XML file, along with a sample of its simulation output, to a database of previously run models.

The GUI is platform-independent, and is being designed to accomodate its future implementation as a web-accessible scientific tool.

1.3. People

The initial design and prototype of the GUI was produced by JohnStavrakakis. As of February 2006, continuing development of the GUI is now looked after by SheaGoyette.

Development of the UnderworldGUI is supervised by Dr. Dietmar Müller (Department of Geosciences, USyd), who oversees the conceptual design of the application, and Dr. Masa Takatsuka (Vislab), who looks after the overall management of the project.

For specific information about the development team or the current state of the project, please visit the [http://wiki.vislab.usyd.edu.au/moinwiki/UnderworldGUI UnderworldGUI page] on the [http://wiki.vislab.usyd.edu.au/moinwiki Vislab Wiki].

2. Installation

2.1. Underworld

Detailed information on how to install Underworld and what sorts of things you can do with the software can be found at the [http://www.mcc.monash.edu.au/twiki/view/Software/Underworld Underworld page] on the [http://www.mcc.monash.edu.au/twiki/view Monash Wiki]. Since I had a few dramas installing the Underworld software suite, though, I thought it might be worth a few moments to write some notes on the additional steps that I took to get it correctly compiled and running.

First of all, I must mention that I'm running Ubuntu Dapper (6.06 LTS). The obstacles I encountered were, for the most part, OS-specific.

Compilers: gcc/g++, g77, mpich, python (alternatively, you could probably use any C/C++, Fortran, and MPI compilers, but for the former two it's probably better to stick with the GNU option).

Be sure to install the dev package for whichever version of python you're running.

Library Dependencies: doxygen, libavcodec-dev, libglut3-dev, libxml2-dev, petsc-dev (required for successful configuration) libfame-dev, libhdf5-mpich-dev, libosmesa6-dev, libsdl1.2-dev (required to eliminate configuration warnings)

This is by no means an exhaustive list, but many of the dependencies including libPNG, libJPEG, and libTIFF are part of the standard Ubuntu installation. The reamining packages can be downloaded using the Synaptic Package Manager (System->Administrator->Synaptic Package Manager). You may have to enable access to community maintained packages by selecting Settings->Repositories, and selecting the (Binary) Community maintained (Universe) and (Source) Community maintained (Universe) chechboxes under Installation Media. To install the libfame package, you will also need to enable access to non-free packages by editing these entries, and adding multiverse (select the checkbox for the Binary entry, and add 'multiverse' to the end of the components field for the Source entry).

With all of this installed, the configure.sh script in the top-level Underworld2 directory still require a number of environment variables to be set. For some reason, Ubuntu has a different default location for certain libraries and header files (for example, header files are stored in /usr/include, rather than /usr/lib/[LIBRARY]/include). So I use export in my .bashrc file to set the following environment variables:

export EDITOR=pico
export X11_DIR=/usr/lib
export X11_INCDIR=/usr/include
export PETSC_DIR=/usr/lib/petscdir/2.3.0
export PETSC_LIBDIR=/usr/lib/petscdir/2.3.0/lib
export PETSC_ARCH=linux-gnu
export MPI_DIR=/usr/lib/mpich
export PYTHON_DIR=/usr/lib/python2.4
export PNG_DIR=/usr/lib
export PNG_INCDIR=/usr/include
export JPEG_DIR=/usr/lib
export JPEG_INCDIR=/usr/include
export TIFF_DIR=/usr/lib
export TIFF_INCDIR=/usr/include
export LIBFAME_DIR=/usr/lib
export LIBFAME_INCDIR=/usr/include
export LIBAVCODEC_DIR=/usr/lib
export LIBAVCODEC_INCDIR=/usr/include

Note, of course, that you may need to modify some of the directories depending on the version number of your packages (in particular, the pathname of python and petsc are version-dependent). I also set the default text editor to pico (but vi or some other console-based text editor could be substituted), and set PetSC to match my computer's architecture (linux-gnu is fine).

After restarting bash, the configuration is more or less successful! I say "more or less" because the OpenGL and X11 tests fail (which I imagine has something to do with having X.org installed), but Underworld still compiles without a hitch.

The compilation process generates a log file of warnings, make.warning, but the messages are all pretty harmless. The developers have made a [http://www.mcc.monash.edu.au/twiki/view/Software/UnderworldWarnings list of possible warnings], many of which can be safely ignored. No doubt this list is not exhaustive.

For troubleshooting advice, see the InstallingUnderworld wiki.

2.2. UnderworldGUI

To install the UnderworldGUI, first obtain a copy of the software from the UnderworldGUI_Downloads wiki (it is recommended that you download the latest stable release, if available). The UnderworldGUI is distributed as g-zipped tar archive, containing an executable JAR-archive and supporting files.

Windows users: To unpack the distribution, use a decompression tool such as PowerArchiver to extract the folder "underworld" to any location on the hard disk. The distribution should run straight away, by navigating to the topmost directory, and running the file UnderworldUI.bat:

<UNPACK ARCHIVE>
cd underworld
UnderworldUI.bat

Linux/Unix/MacOS users: To unpack the distribution, ensure that gzip and tar are installed on your computer. Alternatively, you can use the decompression tool of your choice, provided it supports the gzip and tar formats. The distribution should run straight away by navigating to the topmost directory, and running the file UnderworldUI:

gunzip underworldGUI-rXXX.tar.gz
tar underworldGUI-rXXX.tar
cd underworld
./UnderworldUI

(where XXX = the revision number of UnderworldGUI that you've downloaded).

Once installed, the distribution should include the following files:

2007-01-19_(guide)_contents2.png

dist/: A directory containing the files that make up the GUI software. Also contains the X.509 certificate that must be installed to allow the GUI to access files stored on the local hard disk, when running the GUI in applet mode.*
UnderworldUI: An executable (shell script) for running the GUI under Unix/Linux/MacOS.
UnderworldUI.bat: An executable (batch file) for running the GUI under Windows.
UnderworldUI.html: A sample webpage for running the GUI as an applet.*

_{* Applet mode is not yet fully supported}

There may be some discrepancies in older versions of the GUI. For example, the X.509 certificate was originally stored in a separate directory named cert. A data directory was present in older distributions when the Underworld Model Library was stored in the installation directory (it's now stored in the .underui subdirectory of the user's home directory). An xml directory was sometimes included, as well, containing some example input files to play around with in the GUI.

3. Getting Started

3.1. A Basic Overview

UnderworldGUI offers the user a variety of methods for creating, editing, and submitting geodynamic earth models, in conjunction with the Underworld software. The main controls of the application are available in two forms: as a menu, and as a toolbar. The toolbar consists of graphical representations (icons) of the commands listed in the menus:

2007-01-19_(guide)_controls.png

These commands allow the user to open and close files, select different views of the data, change log and theme settings, and submit their work to the Underworld for simulation. Thse commands are discussed below.

The main window of the GUI consists of three parts: a menu, a toolbar, and an area for editing Underworld models. The menu and toolbar are essentially equivalent, and you can use whichever set of controls you prefer. When you run the GUI for the first time, the area for editing Underworld models will be blank:

2007-01-29_(guide)_blank.png

A new model is created automatically when the GUI is launched. An Underworld model consists primarily of three types of data:

A number of rheology components that define the objects in the model, their dimensions and what they're made up of.
A number of visualisation components that define how the model is visualised during the simulation.
A number of parameters that pertain to all aspects of the simulation process.

All of these data are stored in an XML file that conforms to the StGermain specification (see [2]).

3.1.1. Open and Closing Models

There are two methods for opening an Underworld model. The first is to open the XML file corresponding to the desired model directly. This method can be understood better in constrast to the second method, but typically this first method simply involves loading an XML file from your local disk. This may be one of the sample input files included with the Underworld software, or any XML file that you've saved on the local disk. The commands for opening and saving files in this manner are located in the File menu, and on the far left of the toolbar:

2006-09-05_(guide)_controls_file.png

The second method of opening an Underworld model is to import the XML file corresponding to the desired model from a library of previous run models. The library may be stored locally on your hard disk, or may be located remotely - you don't need to be concerned with this detail, though, since the operation of retrieving a model from the library in either case is exactly the same. The commands for opening (or importing) files from and saving (or exporting) files to a library are located in the File menu, and on the second group of buttons on the toolbar:

2006-09-05_(guide)_controls_library.png

The use of model libraries is discussed further in the section Model Libraries.

3.1.2. Editing a Model

The model editing capabilities of UnderworldGUI consists of three editors. To reiterate, Underworld models are made up of three kinds of data - rheology components, visualisation components, and parameters - and these data are stored in XML files. This XML representation of the data can be viewed in the Plain Text View:

2007-01-25_(guide)_plaintext_view.png

Editing the model as plain text is powerful, but it is really only suited to expert users, or for making very precise kinds of adjustments to the model. For a more user-friendly approach to the data, the components and parameters can be viewed as name-value pairs in the Parameters View:

2007-01-25_(guide)_parameters_view.png

Editing the model in the Parameters View guarantees compatibility with a particular version of Underworld, and simplifies the process of locating specific components or parameters for adjustment. However, a more visual representation of the visualisation components is available by selecting the Viewport Editor View, which includes a preview of the camera perspective and controls for mapping simulation data to visualisation values:

2007-01-25_(guide)_viewporteditor_view.png

The use of these different views (or editors) is covered in more detail in the section Using the UnderworldGUI: One Example. All of these views can be selected from the Views menu, or from the third group of buttons on the toolbar:

2006-09-05_(guide)_controls_views.png

3.1.3. Submitting Jobs to the Underworld

To sun a simulation of the current model using the Underworld software, the GUI submits the currently open model as input to the Underworld software. This operation is called a job request. The actual location of Underworld may be on your local disk, or on a remote server - but as with the model library, you don't need to be concerned with this detail since the operation of submitting the model in either case is exactly the same. To submit a job request of the current model to the Underworld, select either "Send Job..." from the Run menu, or the last button on the toolbar:

2006-09-05_(guide)_controls_job.png

3.2. Using the UnderworldGUI: One Example

Coming soon!

4. Changing Settings

4.1. Debugging

UnderworldGUI offers two levels of debugging information. Error logging displays messages regarding unexpected behaviour in the operation of the software. Ideally, enabling this option would have no observable effect however, it can provide useful information to the developers in case of unexpected errors. Debug logging displays more mundane messages regarding the normal operation of the software, and can also be useful for tracking down errors. You'll probably find the logging options useful only if you are directly involved in the development of UnderworldGUI, or reporting an error to the developers (see UnderworldGUI_Bugs.

The following is a sample of the debugging output, with the error output highlighted in yellow:

2006-09-05_(guide)_terminal_output_highlight.png

Both debug logging and error logging can be selected from the Logging submenu of Settings menu, or from the fourth group of buttons on the toolbar:

2006-09-05_(guide)_controls_logging.png

4.2. Visual themes

When you use UnderworldGUI, you have a choice of two visual themes! The default theme uses Java's default look-and-feel:

2006-09-05_(guide)_theme_java.png

Alternatively, you can use your system's native theme. Pictured here is the System themed UnderworldGUI running under Ubuntu Linux (actual results may vary, depending on your operating system and its configuration):

2006-09-05_(guide)_theme_system.png

The visual theme can be selected from the Theme submenu of Settings menu, or from the fifth group of buttons on the toolbar:

2006-09-05_(guide)_controls_themes.png

5. Model Libraries