Tutorial for New Users

This section provides a simple guide for compiling and running an example parameter file for the Einstein Toolkit.

One complexity of high performance computing is the heterogeneous environments presented by different resources with different core software installations and local setups. For example, Einstein Toolkit codes require compiling with MPI and then running the resulting application in a batch queue. This complexity is hidden as much as possible in Cactus and accompanying tools such as the Simulation Factory.

The example worked through below assumes that you are using the NSF TeraGrid resource Queen Bee. If you don't have an existing account on Queen Bee you can request an account to use for these examples.

Prepare Tools

On Queen Bee (qb.loni.org), the git and hg clients may not be in your path by default. To add them type:

soft add +python-2.6.4-gcc-4.3.2
soft add +git
export PATH=$PATH:/home/eschnett/mercurial-1.9.3/bin

Download GetComponents to checkout all the components of the Einstein Toolkit, and ensure it is executable:

wget --no-check-certificate https://github.com/gridaphobe/CRL/raw/ET_2011_10/GetComponents 
chmod 755 GetComponents

Download, Configure, and Build

Checkout the Einstein Toolkit using anonymous authentication (this may take a few minutes):

./GetComponents -a http://svn.einsteintoolkit.org/manifest/branches/ET_2011_10/einsteintoolkit.th

This checks out Cactus, the Einstein Toolkit thorns, the Simulation Factory and example parameter files into a directory named Cactus.

Configure the Simulation Factory

mkdir scratch/simulations
cd Cactus
cp simfactory/etc/defs.local.ini.simple simfactory/etc/defs.local.ini
nano simfactory/etc/defs.local.ini

Edit defs.local.ini and replace

• YOUR_LOGIN with your username on Queen Bee
• YOUR@EMAIL.ADDRESS with your usual email address
• YOUR_ALLOCATION with your project allocation on Queen Bee
• YOUR_THORNLIST with manifest/einsteintoolkit.th

Compile Executable

./simfactory/bin/sim build

This may take a few minutes. You may receive an error message that building the utilities failed. This is fine as long as the main executable has been built correctly. You can check this with the command ls exe; if this shows a file cactus_sim, then you are fine.)

Run a Simulation

From the Cactus directory, create a batch queue script and submit it to queue an example simulation:

./simfactory/bin/sim submit static_tov --parfile=par/static_tov.par --procs=32 --walltime=8:0:0

This parameter file sets up a static TOV star (a model of a single neutron star) with a mass of 1.4 solar masses and integrates the combined relativistic fluid dynamics and spacetime evolution equations in time. The spacetime is evolved using the BSSN 3+1 formulation of Einstein's equations and the fluid is evolved using a high resolution shock capturing method.

To check the status of the simulation, use

./simfactory/bin/sim list-simulations

Look at Results

For the following make sure that you have logged in to Queen Bee with X-forwarding enabled, i.e.

ssh -Y qb.loni.org

When the simulation is complete, move to the output directory. On Queen Bee (qb.loni.org) the command will be:

cd ~/scratch/simulations/static_tov/output-0000/static_tov

You should see a number of files with the extenstion .asc. These are 0-D (reductions of 3-D grid functions to scalar values) and 1-D ASCII output files that can be plotted with gnuplot.

In this case it's interesting to look at the maximum of the density (in the file hydrobase::rho.maximum.asc). Start gnuplot with the command:

gnuplot

and at the gnuplot prompt type:

p 'hydrobase::rho.maximum.asc' u 2:3 w lp

This plots the data in column 3 (rho) as a function of the data in column 2 (time).

As can be seen from the plot, the maximum of the density oscillates with decreasing amplitude around the initial value with a small drift upwards. Even though the initial model is supposed to be in equilibrium, numerical errors means that the numerical model is not exactly in equilibrium and it starts to oscillate. The oscillation energy is slowly dissipated by shocks, decreasing the oscillation amplitude, while the star contracts in response, increasing the maximum density.

A consistent picture can be seen by plotting the minimum of the lapse:

p 'admbase::lapse.minimum.asc' u 2:3 w lp

The quantity shows the same features as the maximum of the density, except the drift is downwards. The downwards trend stems from the contraction of the star. As the star contracts, the curvature of spacetime increases slightly. In response, the singularity avoiding lapse condition used here decreases the lapse.

As the oscillations and subsequent drift of the density and the lapse are caused by numerical error, increasing the numerical resolution will decrease these effects.

Additional Example Parameter Files

In addition to the TOV star parameter file, we also provide a couple of vacuum parameter files: ks-mclachlan.par and qc0-mclachlan.par. The first (ks-mclachlan.par) evolves a single isolated rotating black hole with the initial data (M=1 and a/M=0.8) specified in Kerr-Schild coordinates. The second (qc0-mclachlan.par) evolves a binary black hole system using the moving puncture technique. The black holes start at a close separation and only complete about one half of an orbit before merging. You can run these additional parameter files using a similar command in the Cactus directory as for the TOV star above:

./simfactory/bin/sim submit ks-mclachlan --parfile=par/ks-mclachlan.par --procs=32 --walltime=8:0:0

and

./simfactory/bin/sim submit qc0-mclachlan --parfile=par/qc0-mclachlan.par --procs=32 --walltime=8:0:0

Additional Simulation Factory Configuration

The example worked out above works out of the box for the Queen Bee machine. You may also be interested though in configuring the Simulation Factory for your own machine or other Teragrid machines. In this section we provide a quick example of what needs to be changed or considered in simfactory/etc/defs.local.ini in order to configure Simulation Factory for your needs. More specifically we are going to work out an example for the TeraGrid machine Ranger.

Simfactory already knows about Ranger, so we only need to provide the settings specific to your account. To do this, you create a section for Ranger machine in defs.local.ini:

[ranger]
user = YOUR_RANGER_USERNAME
allocation = YOUR_RANGER_ALLOCATION

Each machine has different policies on which file system to use to build your application and run your simulation or how the file system tree is organized. Simulation Factory keeps a database for several different machines. You can peek at simfactory/mdb/machines to have an idea of the list of machines and what the default configuration is for each of them. In particular for Ranger, the configuration for the source code path and the simulation path defaults to '/work/00507/@USER@' and '/scratch/00507/@USER@/simulations' respectively. You may need to change it to reflect the group number (00507 here) you belong to. For example you could set (in the [ranger] section):

sourcebasedir = /work/05555/@USER@
basedir = /work/05555/@USER@/simulations

if your group number is '05555'. With these basic changes to simfactory/etc/defs.local.ini you are all set to configure and build the Einstein Toolkit application on Ranger as well.

Going further

Adding a new machine to Simfactory

This and other topics are explained in the Simulation_Factory_Advanced_Tutorial.

Development version of the Einstein Toolkit

Instead of using the release version listed above, you might want the latest development version. Proceed as above, but download from the trunk:

 (GetComponents from trunk)
 ....  -a http://svn.einsteintoolkit.org/manifest/trunk/einsteintoolkit.th

More about Cactus

The EinsteinToolkit is built on top of Cactus. Development requires some familiarity with it. Start reading

• Introduction to cactus
• Cactus tutorials, particularly the WaveToy demo

Any Problems?

This example should work smoothly on the TeraGrid machines Queen Bee, Ranger, Kraken and Abe. If you have any problems, please send details to users@einsteintoolkit.org.