GSIM- Getting Started for Users

Introduction

This page tries give a brief description how to get started with gsim if you don't plan on doing any development work on the code. It does not attempt to cover everything, it's just a quick reference on how to get started running gsim. For a more complete reference look at the "Gsim Users Guide." Note however that the method described in the "Gsim User Guide" for obtaining a copy of the code are now obsolete, since the switch to CVS. A detailed description of how you can get code under CVS can be found in the CMS guide: HTML  or  postscript.

Obtaining a copy of gsim.

There are two somewhat different scenario's for obtaining a copy of the gsim code, one for on-site users and one for off-site users.

On-site:

Setup the CLAS software environment. This can be done by executing: You can now type use_prod to use the PRODUCTIONversion of the codes (default) or use_dev to use the DEVELOPMENT version. Usually the PRODUCTION version works and is stable, but there have been exception. The script you just sourced will default to PRODUCTION . To have it default to another level of the release you could specify the release you want as an argument: source /apps/..../jlab.cshrc DEVELOPMENT  or even source /apps/..../jlab.cshrc release-3-2

(You may wish to add this to your .login or .cshrc file.)

At this point you could just continue running the standard production version of gsim_int or gsim_bat, which you find in the $CLAS_BIN directory. You can also retrieve your own copy of the sources by executing:

cvs checkout -r release-3-2 gsim gsim_int gsim_bat include

This will give you a copy of release-3-2 ( of course you can substitute other release levels after the -r switch) of all the source files needed to compile a copy of libgsim.a and gsim_int and gsim_bat.  To get the very latest, checkout a copy using the -A switch: cvs checkout -A gsim ...
Note that with the new Makefile you can build a copy of gsim_int (gsim_bat) by checking out only gsim_int (gsim_bat) and the routines from gsim you intend to modify. See New Features for a detailed example.

Off-site:

If your computer is not part of the TJAF cluster, you need to go through a number of extra steps. I will just outline them here, since what is really needed in such a situation is to assign a designated librarian on your local system, who maintains the code and builds all the CLAS libraries. If you have a librarian, contact him/her about how to tap into the local sources. If you don't have a librarian READ THE CMS GUIDE !

I assume that you have the necessary software installed on your system: cvs, gnu make, Fortran compiler (f77 or g77), c compiler (gcc), cernlibs, Motif Libraries. (Note that all these except for Motif are standard on a Linux system, and are available for all other platforms. Contact your system administrator if something is missing.)

You now setup the cvs system by executing:

setenv CVSROOT :pserver:USERNAME@jlabs1.cebaf.gov:/group/clas/clas_cvs
cvs login
where USERNAME is substituted by your TJNAF username. Make sure ou are in the "CLAS" group, else you will not have access to the repository. Next you want to check out the entire software tree: At this point you want to copy the file ./packages/cms/offsite.cshrc to reflect the situation on your local system. Copy this file, edit it, and then source your own copy: (from the "packages" directory) Unfortunately this may not work quite so smooth, and you may have to go into each sub directory and "make lib" each library there individually. If you want a more "safe" copy of the code (at least it will compile) you can use a tagged release. This is done when you checkout the code, by using the following command:
  Note that the release switch is "sticky" and will stay in effect until you use a "-A" switch.

You need as a minimum the following libraries: libbos.a libfpack.a libgsim.a librecutl.a libfputil.a libclasutil.a plus all CERNLIB.
For IBM AIX systems there are some particular problems, see Known Problems and Fixes.

Running gsim_int or gsim_bat:

Once you have obtained a copy of the executables, you are ready to start up gsim. Because there are quite a few options that are usually needed to start gsim, you probably want to start it up from a small shell script. Create a file startgsim with the following lines:
$CLAS_BIN/gsim_int -ffread ffread.in \
-mcin "MY_OWN_MCIN_FILE" \
-kine 1 \
-bosout gsim.evt
The "MY_OWN_MCIN_FILE" is obviously replaced with an input file for GSIM. An example file is tests/gsim/mcin_all_4GeV_1k.bfp which was generated using celeg with the input file tests/gsim/celeg_input_4GeV_all.ftn15. (Both files are in the packages directory.) These files represent 1000 events with a 4 GeV beam onto a hydrogen target, with all resonance's (in celeg) turned on.
(Note that since $CLAS_BIN points to the distribution version of gsim_int, you will be running the standard copy. If you want to run your own copy, replace $CLAS_BIN with the path name to your own executable.)

This example also assumes that you are on the TJNAF cluster, or have checked out the tests/gsim area with the gsim input data. It will write an event to a BOS file called gsim.evt for each trigger you give to gsim (using trig # at the prompt or -trig # in the startgsim script.) This BOS file contains all the information about the events, and can be analyzed with recsis. Next create an other file called ffread.in with the following lines:

Please look at the FFREAD page for more detail.
Now this file is ofcourse quite personal, and I would by no means claim that this is the best example, it is just what I happen to have used last. There are many different parts to the detector and a lot of different switches called FFREAD cards. Each of these cards affects one part of the detector or an other, the details of which are in the GSIM User Guide, the GEANT Manual, the New Features web page, or the code itself.

To get a pretty picture like the one on the main page you now execute the following commands at the command prompt:

This picture will not be identical the one on the main page, since many things will have changed between the creation of that picture and your running the code. However, if you generate a number of these pictures, you should see very similar features.

Beyond this, you probably want to start reading manuals, and perhaps code...

Writing your own USER routines:

To get specific output out of gsim, you will need to write your own guser_*.F routines. A template for these routines are found in the packages/gsim directory. Details of how to do this are in the "Getting Started: Developers" page.