Underworld

a long term geodynamics simulation platform

Compiling Underworld With SCons

Why SCons and not VMake?

SCons must be used to compile releases Underworld-1.2.0 and later. Underworld-1.1.0 and earlier releases were compiled using VMake.

Some Notes About SCons

  • Environment variables are used when configuring
  • All configuration steps are logged in 'config.log'
  • Can only build from the project root, which guarantees consistent builds.

Compiling Underworld-1.4 and the Bleeding Edge Version of Underworld

These instructions apply to compiling on local linux and mac machines, and broadly apply to compiling on clusters as well. However for specific instructions for each of a range of supported computer clusters, follow the links on the Cluster page.

Underworld-1.4 and the "Bleeding Edge" version of Underworld both come with a copy of SCons, so there is no need to download and install your own copy of SCons separately.

Step 1: Configure

No additional configuration conditions should be necessary on local linux machines, or macs with Mac OSX version >=10.6. Macs using Mac OSX <10.6 will need to add the following flag (because Carbon is supported) to the end of their configuration command: 

--with-x11=0

For supported computer clusters follow the links on the Cluster page.

If you have more than one build of your MPI implementation and / or PETSc, ensure that you have environment variables and the path set for the builds that you want to use when configuring Underworld.

Navigate into the directory you checked out or downloaded, and type:

optimised:

  • good if you are not going to be developing a lot of code but are going to be doing a lot of runs
  • you should use optimised builds of your MPI implementation and PETSc. Why? The majority of the time used by the code is spent in the Solvers.
./configure.py --with-debugging=0

debug: 

./configure.py --with-debugging=1

A list of dependency checks will be returned, which you should review for any specific dependencies that you want to ensure have been identified. If the configuration step has completed successfully (in terms of minimium requirements to compile the code), you should see: 

Successfully configured.

Step 1a: Getting help

For help, read the "README" document that comes with your checkout of Underworld. For additional compile options, type: 

./configure.py -h

Step 2: Build

In the same directory, then type: 

./scons.py

or for code developers who want to rebuild as fast as possible (note that this is not garaunteed to produce a consistent build): 

./fast-scons.py

Step 3: Check Build

To run tests, type one of the following (note that on a cluster this may have to be run / submitted as an mpi job):

   1. runs unit-tests & low resolution integration tests

./scons.py check

   2. runs only convergence tests

./scons.py check-convergence

   3. runs all tests (recommended for cluster installs, however can take a long time and backfire on machines with a complex mpi environment)

./scons.py check-complete

Compiling Underworld-1.2.0

Step 1: Download and Install SCons

SCons must be installed as an external package before compiling Undeworld-1.2.0. See SConsDownload for instructions on how to install SCons

Step 2: Configure

If you have more than one build of your MPI implementation and / or PETSc, ensure that you have environment variables and the path set for the builds that you want to use when configuring Underworld.

Navigate into the directory you checked out or downloaded (e.g. Underworld_1_2_0) and type:

optimised:

  • good if you are not going to be developing a lot of code but are going to be doing a lot of runs
  • you should use optimised builds of your MPI implementation and PETSc. Why? The majority of the time used by the code is spent in the Solvers.

- for linux and macs: 

scons config with_optimise=1

- for clusters at NCI NF (xe) and VPAC (tango): 

scons config with_optimise=1 with_x11=no

debug:

- for linux and macs: 

scons config with_debug=1

- for clusters at NCI NF (xe) and VPAC (tango): 

scons config with_debug=1 with_x11=no

Step 2a: Getting help

For a list of the SCons default configuration settings, navigate into the directory you checked out or downloaded (e.g. Underworld_1_2_0) and type the following: 

scons help

Step 3: Build

In the same directory, then type: 

scons

-- Wendy Mason - 12 April 2010
-- Julian Giordani - 12 April 2010
-- John Spencer - 13 Aug 2008
-- Luke Hodkinson - 13 Aug 2008