Chapter A1
Getting Started

A1.1 Obtaining Cactus

Cactus is distributed, extended, and maintained using the free Subversion software (http://subversion.apache.org/docs/) SVN allows many people to work on a large software project together without getting into a tangle. Since Cactus thorns are distributed from several repositories on the main SVN site, and from a growing number of user sites, we provide a GetComponents script on our website for checking out the flesh and thorns. The script is available at

https://github.com/gridaphobe/CRL/raw/ET_2011_10/GetComponents.

The script takes as an argument the name of a file containing a ThornList, that is a list of thorns with the syntax

<arrangement name>/<thorn name>

Optional directives in the ThornList indicate which repository to fetch thorns from. The ThornList is written in the Component Retrieval Language, documented at https://github.com/gridaphobe/CRL/wiki/Component-Retrieval-Language.

The same script can be used to checkout additional thorns, or to update existing ones.

The components that make up Cactus can also be checked out directly using SVN from http://svn.cactuscode.org.

Another script, MakeThornList, can be used to produce a minimal ThornList from a given Cactus par file. It needs a master ThornList to be copied into your Cactus directory.

See http://cactuscode.org/download/thorns/MakeThornList.

A1.1.1 Directory Structure

A fresh checkout creates a directory Cactus with the following subdirectories:

.svn

the SVN bookkeeping directory, present in every subdirectory

doc

Cactus documentation

lib

contains libraries

src

contains the source code for Cactus

arrangements

contains the Cactus arrangements. The arrangements (the actual “physics”) are not supplied by just checking out just Cactus. If the arrangements you want to use are standard Cactus arrangements, or reside on our SVN repository (svn.cactuscode.org), they can be checked out in similar way to the flesh.

When Cactus is first compiled, it creates a new directory Cactus/configs, which will contain all the source code, object files and libraries created during the build process.

Configurations are described in detail in Section A1.2.1.

A1.2 Compiling a Cactus application

Cactus can be built in different configurations from the same copy of the source files, and these different configurations coexist in the Cactus/configs directory. Here are several instances in which this can be useful:

  1. Different configurations can be for different architectures. You can keep executables for multiple architectures based on a single copy of source code, shared on a common file system.
  2. You can compare different compiler options, and debug-modes. You might want to compile different communication protocols (e.g. MPI or Globus), or leave them out all together.
  3. You can have different configurations for different thorn collections compiled into your executable.

A1.2.1 Creating a Configuration

At its simplest, this is done by gmake <config>. This generates a configuration with the name config, doing its best to automatically determine the default compilers and compilation flags suitable for the current architecture.

There are a number of additional command-line arguments which may be supplied to override some parts of the procedure; they are listed in Section B2.1.

Once you have created a new configuration, the command

gmake <configuration name>

will build an executable, prompting you along the way for the thorns which should be included. There is a range of gmake targets and options which are detailed in Section B2.4.1.

A1.3 Running a Cactus application

Cactus executables always run from a parameter file (which may be provided as a command-line argument taken from standard input), which specifies which thorns to use and sets the values of each thorn’s parameters (the parameters that are not set will take on default values, see D2.3).

There is no restriction on the name of the parameter file, although it is conventional to use the file extension .par. Optional command-line arguments can be used to customise runtime behaviour, and to provide information about the thorns used in the executable. The general syntax for running Cactus from a parameter file is then

./cactus_<config> <parameter file> [command-line options]

A parameter file is a text file whose lines are either comments or parameter statements. Comments are blank lines or lines that begin with either ‘#’ or ‘!’. A parameter statement consists of one or more parameter names, followed by an ‘=’, followed by the value(s) for this (these) parameter(s). Note that all string parameters are case insensitive.

The first parameter statement in any parameter file should set ActiveThorns, which is a special parameter that tells the program which thorns are to be activated. Only parameters from active thorns can be set (and only those routines scheduled by active thorns are run). By default all thorns are inactive. For example, the first entry in a parameter file which is using just the two thorns CactusPUGH/PUGH and CactusBase/CartGrid3D should be

ActiveThorns = "PUGH CartGrid3D"

Parameter specifications following ActiveThorns usually are carried out by listing the name of the thorn which defined the parameter, two colons, and the name of the parameter — e.g. wavetoyF77::amplitude (see Section C1.4.2 for more information).

Notes: