Kranc Tutorial

This tutorial is in four parts. The first part describes how to download and configure Cactus, and can be skipped if you are already familiar with Cactus and have an existing Cactus installation that you want to use. The second part describes how to download and install Kranc into your Cactus installation. The third part describes how to generate the SimpleWave example thorn and compile it. The fourth part describes how to run the example and analyse the output.


Download and install Cactus

The first step is to create a Cactus directory. Everything will then be downloaded into this directory and compiled there.

mkdir Cactus
cd Cactus

Download the Cactus GetComponents script and make it executable. This script allows you to download Cactus thorns from many different repositories listed in a ThornList.

curl -kLO
chmod u+x GetComponents

Download Cactus:

./GetComponents -a --root=.

After several minutes, Cactus should have been downloaded.

Install Kranc into your Cactus directory

Download the Kranc distribution (you will need the git version control program installed):

git clone git://

Link Kranc into your Cactus installation:

ln -s ../Kranc/Auxiliary/Cactus/KrancNumericalTools arrangements/KrancNumericalTools
ln -s ../Kranc/Examples arrangements/KrancExamples

Kranc is now installed and ready to use.

Build the SimpleWave example

Go into the Examples directory and run Kranc to build the SimpleWave thorn:

cd Kranc/Examples
../../Kranc/Bin/kranc SimpleWave.m

There should be a new directory, SimpleWave, which is the Cactus thorn which has been newly generated from the SimpleWave.m Kranc script.

Return to the Cactus directory and copy the example Cactus thornlist:

cd ../..

Add KrancNumericalTools/GenericFD and KrancExamples/SimpleWave to using a text editor or the following command::

echo 'KrancNumericalTools/GenericFD
KrancExamples/SimpleWave' >>

Create a Cactus configuration called "kranc" using this thornlist:

make kranc-config PROMPT=no

If a C compiler cannot be found, or there is some other error, consult the Cactus documentation for advice on configuring Cactus for your system. You may have to write an optionlist for your system and use it in the "make kranc-config" line.

The configuration containing the Kranc-generated thorn should now have been built. The executable will be exe/cactus_kranc and the intermediate build files will be in configs/kranc.

Run the SimpleWave example

Run Cactus with the parameter file simplewave_sine.par:

cd Kranc/Examples
../../exe/cactus_kranc simplewave_sine.par

You should see many lines of output as Cactus runs. If the test finishes successfully, the final line should be "Done."

The output will be in the directory simplewave_sine. The variable phi is stored as a 1D timeseries in simplewave_sine/phi.xl. The output file is a simple text file which can be visualised in Mathematica using the provided Analysis.nb notebook, or in the ygraph animation tool.

To visualise the output in Mathematica, open the notebook "Analysis.nb", provided in the Examples directory, and choose Evaluation -> Evaluate Notebook.

You should see a sine wave. Use the Manipulate slider to animate the display to see the different iterations of the simulation.

Plot of sine wave