Underworld

a long term geodynamics simulation platform

Updating Underworld

Note on modifying files within the Underworld

It is recommended that you do not modify any of the files within your copy of Underworld or its subdirectories, but instead locate all of your own files (which can then call template files) outside the directory you checked out or downloaded. This is to ensure that the template files within the InputFiles and Viewports directories will remain up-to-date. If you copy a template file and locate the copy within the directory you checked out or downloaded (or its subdirectories), the copy will not be updated and may cease to work after an update.

If you have modified files within Underworld, or added your own new files, it is strongly recommended that you make a copy of all of your modified and new files and store the copies outside the directory you checked out or downloaded prior to running an update.

Note on Updating Releases of Underworld

Each release of Underworld is located in its own separate respository (e.g.v1.2.x), which is different to the central Underworld repository that is updated regularly. When you run an update (see below), a 'release' will only update with any improvements that have been made to that particular build.

No release copy of Underworld can be updated to the development "Bleeding Edge" version of Underworld, which instead must be downloaded and installed separately.

Note on Underworld Major Structure and Dependency Changes

For copies of Underworld downloaded or updated on or after 17 January 2007, the locations of template InputFiles changed, and for MacOSX mpich 2 is required as the mpi implementation (see MpiDownload).

Note on Keeping Environment Variables Up-to-date

When updating your copy of Underworld to a later version, before you compile the updated version check first that your environment variables are still up-to-date (for example that they are pointing to the latest versions of each software dependency). If you update your .bashrc file (if using bash), remember to source your .bashrc file after making amendments to update your environment variables. If you require instructions on how to edit your .bashrc file and environment variables, please refer to the Environment Variables Checklist.

How Do I Know What Version of Underworld I Have?

To obtain information about the version of your copy of Underworld, navigate into the directory you checked out or downloaded (e.g. Underworld_1_4) and (for a copy checked out using Mercurial repository) type one of the following, depending on the information you seek (internet access required).

For the current revision status: 

hg parent

For the central repository location: 

hg paths

For a list of other hg commands, type: 

hg help

To identify the repository each directory of your copy of Underworld was checked out from: 

./identify-all.sh

Running an Update on the Whole of Underworld

The following instructions outline how to update a copy of Underworld (including its subdirectories), which was checked out from a Mercurial repository (Underworld-1.2.0 onwards) with any improvements that have been made within the repository from which you originally downloaded it. For example, if you downloaded from the Underworld-1.4 repository, you will be updated to the latest version of Underworld-1.4 (see the Installation Guide for further information on downloading different versions of Underworld).

Open a terminal window, navigate into the directory you checked out or downloaded (e.g. Underworld_1_4), and type (internet acces required): 

hg fpull
hg fup

(you may be prompted several times for your usernames and passwords). Then recompile your copy of the code using SCons (for copies of UnderWorld checked out after to 7 Aug 2008).

Updating only a Subdirectory of Underworld

Under normal circumstances, if you wanted to update your copy of Underworld, you would update the whole directory that you checked out or downloaded, as detailed in the section above. However in some cases, such as if instructed by a code developer or helpdesk, you may only need to update a particular subdirectory (such as PICellerator, StGermain, StgFEM, Underworld or gLucifer) with updated files that correct a particular problem you may have been experiencing.

The following instructions outline how to update only a particular subdirectory of a copy of Underworld (and further subdirectories within the subdirectory), which was checked out from a Mercurial repository (Underworld-1.2.0 onwards) with any improvements that have been made within the repository from which you originally downloaded your copy. For example, if you downloaded from the Underworld_1_4 repository, you will receive any improvements that have been made to the subdirectory of that particular release (see the Installation Guide for further information on downloading different versions of Underworld).

Open a terminal window, navigate into the particular subdirectory (such as PICellerator, StGermain, StgFEM, Underworld or gLucifer) and type (internet access required): 

hg fpull
hg fup

(you may be prompted several times for your usernames and passwords). Then recompile your copy of the code using SCons (Underworld-1.2.0 onwards).

-- Wendy Mason - 13 January 2010