TWIST Software Installation Guide

To analyse data, both real and simulated, TWIST uses software named MOFIA. To generate simulation data, TWIST uses the software GEANT. You need to download and compile the latest versions of these two pieces of software. This guide will take you through the process step-by-step.

Before you start this guide, you will need an account on the TWIST Linux Cluster.

Setup cvs access
Get sources from cvs
Setup your login scripts
Build the software
Get the CFM and caldb_ascii databases
Generate and analyze a GEANT data file
Additional information

This guide assumes that you are using the "tcsh" shell. Do not use the "sh" and "bash" shells with this guide. To find out the name of your default login shell, use the echo $SHELL command. If your login shell is not "tcsh", use the tcsh command to enter the "tcsh" shell.

Setup CVS access

Both MOFIA and GEANT undergo constant development. TWIST uses the software CVS (Concurrent Versions System) to keep track of changes in source code. The CVS repository is a single copy of the source code at a particular time. You need to 'check out' the latest version of MOFIA and GEANT from the CVS repository. First you need to make some settings.

Check your account is a member of e614cvs. To do this, use the command id. The output must have e614cvs listed.

CVS needs environment variables to be set. Add the following lines to the file .tcshrc in your home directory (you may need to create this file):

  setenv CVS_RSH ssh
  setenv CVSROOT /home/e614mgr/cvs

If you are off-site, you will need to use

  setenv CVSROOT username@twist.triumf.ca:/home/e614mgr/cvs

The .tcshrc script is run each time a terminal is started. Open a new terminal, and check the environment variables are set using:

  echo $CVS_RSH
  echo $CVSROOT

Now setup the basic directory structure:

  mkdir $HOME/e614soft
  cd $HOME/e614soft
  cvs checkout -d triumf admin

Get the sources from CVS

The CVS repository contains several versions of MOFIA and GEANT. Each time a version passes quality assurance testing, it is said to be 'stable' and is then 'tagged'. There are also development versions that contain the latest bug fixes, but the code quality is not guaranteed. Development versions are 'untagged'. We recommend that you checkout the development versions.

To checkout from cvs, we will use the command cvs checkout.

Move to the MOFIA directory using

cd $HOME/e614soft/triumf/mofia.

Then checkout one of the MOFIA versions:

mofia devel: (recommended)
```
  cvs checkout -d devel mofia
```
mofia, Westgrid tag: (e.g. wg_2_3)
```
  cvs checkout -d wg_2_3 -rwg_2_3 mofia
```
for other versions, go to bottom of page.

From the above two examples, you can see that the cvs checkout has the options:

-d subdirectory_name
-rtag
mofia OR geant

Now move to the GEANT directory using

cd $HOME/e614soft/triumf/geant

Then checkout one of the GEANT versions:

geant devel: (recommended)
```
  cvs checkout -d devel geant2
```

geant, Westgrid tag: (e.g. wg_g3_4):

  cvs checkout -d wg_g3_4 -rwg_g3_4 geant2

geant 2.1.3:
```
  cvs checkout -d 2.1.3 -rv2-1-3 geant2
```
for other versions, go to bottom of page.

If you are off-site, you may also need to check out the support packages (however, generally you should work with support packages installed in ~e614/e614soft/...). To check these out, follow the instructions here.

Setup the login scripts

The script .tcshrc is executed every time a new shell is started. After this script, .login is then executed, but only when you initially log in. The .login file is the preferred location for environment variables.

Open your .login file for editing and add:

  source /home/e614/e614soft/triumf/setup.com

This will give you the "standard" TWIST setup for environment variables.

If you prefer to use your own setup script, then add:

  source $HOME/e614soft/triumf/setup.com

and edit this file to personalise your setup.

The standard environment can be overriden by setting environement variables before the source setup.com command. Most of the defaults chosen by the setup script would work for most users. Of note, the setup scripts automatically sets ROOTSYS, ABSOFT and the CERN library paths. Local users at triumf may want to override only MOFIA_COMMANDS, GEANT_COMMANDS, and GEANT4_COMMANDS, while remote users would have to provide site-specific settings for TRIUMF_ROOT, E614_CAL, ROOTSYS,CERN_LIBRARY, CERN_LIBRARY_ABSOFT and CVSROOT. For a full list of user-settable environment variables, click here.

Build the software

To build both mofia and geant you must be on the computer 'bench'. To get there, ssh username@bench.triumf.ca.

To build MOFIA:

mofia is built by the F90 compiler 'icc8', although this may change in the future. To build the development version, use the following commands:

          setenv MOFIA_COMMANDS $HOME/e614soft/triumf/mofia
	  source $HOME/e614soft/triumf/setup.com
	  setup mofia devel                                        (this can be added to your .login)
	  mlib icc8                                                (instructs which compiler to use)
	  cd $MOFIA_COMMANDS/devel/source/dummy ; make
	  cd ../mainf90; make
	  cd ../main;    make
	  cd ../photo;   make
	  cd ../user;    make                                      (produces .../user/mofia, .../user/photo)

The command mlib can have other arguments. Click here to see them.

If you are building a different version of mofia, then you must change BOTH occurrences of devel. For example, if you are building mofia 2.2.x, then change setup mofia devel to setup mofia 2.2 and cd $MOFIA_COMMANDS/devel/source/dummy ; make to cd $MOFIA_COMMANDS/2.2/source/dummy ; make.

To build E614 GEANT:

Building GEANT requires an F77 compiler (i.e. g77) and installed CERN libraries. To build the development version, use the following commands:

          setenv GEANT_COMMANDS $HOME/e614soft/triumf/geant
	  source $HOME/e614soft/triumf/setup.com
	  setup geant devel                                        (again, this can be added to your .login)
	  mlib g77
          cd $HOME/e614soft/triumf/geant/devel/source
	  make                                                     (produces executable ../bin/bat614)

If you are building a different version of geant, then you must change BOTH occurrences of devel. For example, if you are building geant 2.1.3, then change setup geant devel to setup geant 2.1.3 and cd $HOME/e614soft/triumf/geant/devel/source to cd $HOME/e614soft/triumf/geant/2.1.3/sourcee.

Get the calibration files

If you are onsite and on the TWIST cluster, the setup script will automatically set CAL_DB and CFM_DB to ~e614/e614soft/...

If you are offsite, you can get an up-to-date copy of the calibration files using rsync:

      tcsh% setenv E614_CAL $HOME/e614soft
      tcsh% source $HOME/e614soft/triumf/setup.com
      tcsh% echo $CAL_DB (should print: $HOME/e614soft/caldb_ascii)
      tcsh% echo $CFM_DB (should print: $HOME/e614soft/cfm/db_noswap)
      tcsh% mkdir -p $CAL_DB
      tcsh% mkdir -p $CFM_DB
      tcsh% rsync -avz tw04.triumf.ca::twist_caldb/ $CAL_DB
      tcsh% rsync -avz tw04.triumf.ca::twist_cfmdb/ $CFM_DB

Test the newly built software

Generate a geant file

The settings for a simulation run are kept in a file e614.ffcards. This file must be edited before executing geant.

cd $HOME/e614soft/triumf/geant/devel/run
setup geant devel
edit the e614.ffcards file:
- edit the TRIG card to set the number of events: TRIG 10
- edit the RUNG card to choose a run number for the simulation: RUNG 1
run geant: ./e614.com

After the run, geant generates a log file, data file and histograms in the sub-directory results.

ls -l results should show this:

[xxxx@jam run]$ ls -l results/
total 409
drwxr-xr-x    2 xxxx     users         128 Oct 29 15:22 CVS
-rw-r--r--    1 xxxx     users       32768 Oct 29 16:19 run1.dat    --- GEANT YBOS output file for MOFIA
-rw-r--r--    1 xxxx     users      311296 Oct 29 16:19 run1.hbook  --- GEANT histograms (use paw++)
-rw-r--r--    1 xxxx     users       62055 Oct 29 16:19 run1.log    --- GEANT log file

You should spend a little time seeing the sort of information contained in the log file. Examine it using more results/run1.log

Analyze the geant file you have just generated

Now you will analyse the simulated data using mofia.

      setenv MOFIA_COMMANDS $HOME/e614soft/triumf/mofia
      source $HOME/e614soft/triumf/setup.com
      setup mofia devel
      mlib icc8
      cd $HOME/e614soft/triumf/mofia/devel/source/user                     (this is the directory where the executable photo is found)

      setenv MTIN $HOME/e614soft/triumf/geant/devel/run/results/run1.dat   (tell mofia where to look for the data)
      ./photo

      MOFIA> name global unpackmc=T                                 (set namelist variable so mofia knows data is Monte Carlo)
      MOFIA> set photo on
      MOFIA> ana

(start analysis)

A graphical window with event graphics should open. Try out the options and look at a few events. Press the "exit" button when you are done, and type exit or use CTRL-C to exit mofia.

Analyze a raw data file

TWIST carries out the same analysis on simulation and real data. The raw data files look the same. So far you have looked at event graphics for simulated data. You will now look at a raw data file.

List the contents of the datalinks directory using:

  ls /home/e614/datalinks/

These are the data runs that are locally available (other runs must be retrieved from tape). Choose a directory and then a run. Files with real data end in .ybs Now analyse the data using the following commands:

      setenv MOFIA_COMMANDS $HOME/e614soft/triumf/mofia
      source $HOME/e614soft/triumf/setup.com
      setup mofia devel
      mlib icc8
      cd $HOME/e614soft/triumf/mofia/devel/source/user
      (so far this is the same as previously)

      setenv MTIN /home/e614/datalinks/directory/runrunnumber.ybs    (put in your choice of run here)
      ./photo

      MOFIA> set photo on                (no longer need to set unpackmc)
      MOFIA> ana 10                      (analyse 10 runs)

Again, play with the Graphics to get an overview of the detector and what an event looks like.

If you have got this far, then you have mofia and geant working!

Additional Information

Other versions of mofia and geant

Remember to move to the MOFIA directory before checking out. Use

cd $HOME/e614soft/triumf/mofia

The other versions of mofia are:

mofia 2.2.YYMMDD: (see weekly tags)

  cvs checkout -d 2.2 -rMOFIA-2-2-YYMMDD mofia

mofia 2.2.2:

  cvs checkout -d 2.2 -rMOFIA-2-2-2 mofia

Remember to move to the GEANT directory before checking out. Use

cd $HOME/e614soft/triumf/geant

The other versions of geant are:

geant 2.1.2: cvs checkout -d 2.1.2 -rv2-1-2 geant2
geant 2.1.1: cvs checkout -d 2.1.1 -rv2-1-1 geant2
geant 2.1: cvs checkout -d 2.1 -rv2-1 geant2
geant 2.0.1: cvs checkout -d 2.0.1 -rv2-0-1 geant2

GEANT4 is the latest version, not yet fully implemented by TWIST. You can checkout the source code if you wish:

geant4 devel:


          cd $HOME/e614soft/triumf

          cvs checkout geant4/setup.com

          cd $HOME/e614soft/triumf/geant4

          cvs checkout -d devel geant4

To build E614 GEANT4:

Building GEANT4 requires clhep libraries as well as various visualization libraries, which are available on bench.

Build geant4 devel:

          source $HOME/e614soft/triumf/setup.com
          setenv GEANT4_COMMANDS $HOME/e614soft/triumf/geant4
          setup geant4 devel
          mlib g77 
          cd $G4F77/src
          make
          cd $G4ROOT
          make  (produces executable $G4ROOT/bin/Linux-g++/twist)

Build geant4 devel debug:

         source $HOME/e614soft/triumf/setup.com
         setenv GEANT4_COMMANDS $HOME/e614soft/triumf/geant4
         setup geant4 devel debug 
         mlib g77 debug
         cd $G4F77/src
         make
         cd $G4ROOT
         make  (produces executable $G4ROOT/bin/Linux-g++/twist)
         make install move $G4ROOT/bin/Linux-g++/twist $G4ROOT/bin/Linux-g++/twist_dbg

To build the support libraries:

(to be written and tested...)

Support Packages

If you are offsite, you may need to check out the following support packages:

bru:: cd $HOME/e614soft/triumf/bru cvs checkout -d 1.1 bru
cfm:: cd $HOME/e614soft/triumf/cfm cvs checkout -d 2.2 cfm
ybos:: cd $HOME/e614soft/triumf/ybos cvs checkout -d 4.1 ybos
gplot:: cd $HOME/e614soft/triumf cvs checkout gplot

Environment Variables

Here is the full list of user-settable environment variables:

TRIUMF_ROOT: location of the standard twist software.
E614_CAL: location of the CFM database.
TRIUMF_SCRIPTS: location of twist setup scripts and makefiles.
ROOTSYS: location of the ROOT installation.
CERN_LIBRARY: location of the g77-compiled CERN library
CERN_LIBRARY_ABSOFT: location of the ABSOFT-compiled CERN library
CVSROOT: location of the twist code repository
GPLOT_DIR: location of the GPLOT library
BRU_COMMANDS: location of the BRU library
MOFIA_COMMANDS: (see section on building mofia)
GEANT_COMMANDS: (see section on building geant)
GEANT4_COMMANDS: (see section on building geant4)
CFM_COMMANDS: location of the CFM library
YBOS_COMMANDS: location of the YBOS library
ABSOFT: location of the ABSOFT F90 compilers

mlib options

You can check the possible mlib options using mlib -h. Some useful mlib options are:

g77 - use the GCC F77 compiler
icc8 - use the Intel compiler
debug - compile code for debugging, also enables array bounds checks
profile - compile code for profiling
nocheck - disable array bounds checks. Use this only on files that cause ABSOFT to dump core.

Last updated Fri Mar 3 2006 by

James Bueno

This is a modification of the original guide written by

Konstantin Olchanski