Simulation Factory Advanced Tutorial

The Simulation Factory is an effective method for controlling all facets of a Cactus simulation. It provides a central facility for managing an authoritative source tree, controlling and providing remote access to many commonly-used HPC machines including LONI and the TeraGrid, builds and compiles a Cactus source tree into many independent configurations, and can also manage a simulation all the way from creation to output.

Getting Started

In order to begin using The Simulation Factory, it must be checked out from svn. The Simulation Factory typically resides in the simfactory folder inside a Cactus source tree. This can be accomplished with the following svn command:

svn co https://svn.cct.lsu.edu/repos/numrel/simfactory/branches/PYSIM_2010 simfactory

The Simulation Factory can also be placed in an independent location to be used with multiple Cactus source trees. This approach will be detailed later.

Initial Setup

Once The Simulation Factory has been checked out from svn, the next step is to create two required configuration files. Assuming The Simulation Factory has been checked out into the simfactory folder, this initial configuration can be accomplished with the following commands:

cp simfactory/etc/defs.ini.example simfactory/etc/defs.ini
cp simfactory/etc/defs.local.ini.simple simfactory/etc/defs.local.ini

Edit simfactory/etc/defs.local.ini and replace

• YOUR_LOGIN with your usual username
• YOUR@EMAIL.ADDRESS with your usual email address
• YOUR_ALLOCATION with your usual allocation

Additional Configuration

The Simulation Factory contains a database known as the Machine Database. This collection of information is used to define and help mitigate the uniqueness of each individual HPC machine. The Machine Database is an authoritative collection of information, and is generally not meant to be edited by a user. To add, or change properties of a Machine Database entry, simfactory/etc/defs.local.ini is used. For instance, if an alternative username, allocation, and sourcebasedir is needed for the machine queenbee, you would add the following section:

[queenbee]
user          = queenbee_username
allocation    = queenbee_allocation
sourcebasedir = /work/@USER@

There are several macros that can aide in simplifying configuration. For configuration purposes, the most useful is @USER@. This macro expands to the user property of the Machine Database entry. If user was defined in the [default] section of simfactory/etc/defs.local.ini then it will contain that value. An expanded list of useful macros can be found in the #Macros section

To get a list of preconfigured machines, issue the following command:

simfactory/sim list-machines

Local Workstation Configuration

In order to use a local workstation with The Simulation Factory, a Machine Database entry must be created. Before getting started, the hostname of the local machine must be determined. It is through this hostname that The Simulation Factory matches a Machine Database entry to the executing machine. The hostname can be determined using the following command:

hostname

Once you have the hostname, issue the following command:

cp simfactory/etc/mdb/generic.ini simfactory/etc/mdb/<hostname>.ini

Edit simfactory/etc/mdb/<hostname>.ini and replace

• [generic] with [<hostname>]
  • The section header for this machine database entry must be a unique value and must match the nickname property exactly.
• nickname = generic with nickname = <hostname>
• hostname = generic with hostname = <hostname>
• sourcebasedir = /home/@USER@ with the correct root path under which all your Cactus source trees reside.
• basedir = /home/@USER@/simulations with the desired folder for simulation output

user, email, and allocation can safely be ignored, as the values from the [default] section of simfactory/etc/defs.local.ini will propagate to this entry.

Accessing Remote Systems

The Simulation Factory provides a convenient facility for handling remote communication and file transfer with any known machine. Using this facility, a user can synchronize an authoritative source tree, get an interactive shell on the remote system, or execute a command, locally or remotely.

Information Commands

The following commands can be used to discover information about a machine, or list all known, configured machines.

List all known machines

simfactory/sim list-machines

List details about a single machine

simfactory/sim list-machine <machine>

Print the current Machine Database to the screen

simfactory/sim print-mdb

Get the machine that The Simulation Factory is currently being executed on

simfactory/sim print-machine