Event Generators for STAR and User Tutorial

 

(Prepared by Ron Longacre and edited by Lanny Ray.)

In this tutorial you will learn the following:

• What event generator files exist in the STAR portion of the RCF Managed Data Store and how to retrieve these onto disk.
• How to examine the particle distributions predicted by the generators using STAF and PAW.
• How to run the event generator VENUS.
• How to add particles or, in general, how to modify an event generator file.
• How to load the event generator output into STAF tables and examine the particle distributions using STAF and PAW.

Setup To run this tutorial you must login to one of the RCF SGI-irix machines, the preferred choices are:

• rsgi00.rhic.bnl.gov
• rsgi05.rhic.bnl.gov

Login to one of these computers, klog if necessary to get an AFS token, then setup a safe scratch directory for this tutorial. You should use one of the STAR scratch disks such as /scr20, /scr21 or /scr22. To do so, for example, change directories by typing

cd /scr20

and create a local subdirectory for your own use by typing

mkdir ``your_name''

where you must substitute your user name (or other suitable name) in place of ``your_name''. Change directories to this new subdirectory by typing

cd /scr20/``your_name''

Next, copy the necessary files for this tutorial into this area by entering

cp -r /star/trga/tut .

This creates a subdirectory /``your_name''/tut and puts a lot of files in it. Change to this directory and list the files:

cd /scr20/``your_name''/tut

ls -l

The files in the directory are:

• VENUS - an executable binary for the program VENUS-4.12 for SGI-irix.
• auau_fght_minb - a script for running VENUS.
• evgen.xdf - an xdf output file from a VENUS run.
• gst2xdf - a special STAF executable that translates the text file output from an event generator, in this case venus.gst, into an xdf format file. This version runs only on SGI-irix.
• sisi_fght_cent - another script for running VENUS.
• test.kumac - a test kumac that we will run as part of this tutorial.
• tutorial.html - this is a previous tutorial page.
• venus.gst - a text format output file produced by VENUS.

STAR Event Generator Output File Library

Various groups in STAR (mainly the Trigger group) have generated a great number of events for simulation studies. So far, these have mostly been stored in the 3 TByte Managed Data Store (tape robot). The event generator codes produce a list of particles and momenta, production and decay vertices, parent - daughter relationships, etc. in one of the following output formats:

1. Zebra - the old CERNLIB compressed data format, no longer used in STAR for event generator output files.
2. Old Text Format - a simple list of particles and momenta.
3. New GSTAR Text Format - the current, preferred output text format which is explained in detail in the GSTAR Proposal and Manual.

The GSTAR text format files were converted into STAF datasets and saved as xdf files. This is done by running a special, standalone STAF executable called gst2xdf which reads the text files and copies the data into a STAF dataset for event generator output, filling the following tables:

• eg_gener - contains the code version number, beam characteristics, maximum impact parameter.
• eg_event - contains event characteristics.
• eg_texture - contains event topology information.
• eg_track - contains particles and momentum information.
• eg_vertex - contains vertices.

This code then outputs the event generator STAF dataset and tables as an external, saved xdf file, which the user may subsequently move to the MDS.

The event generator directory hierarchy on the MDS is organized as follows:

• Top Level: /star/mds/data
• Data Set Level: SD96 SD97
• Reaction Level: auau200 auau30 cucu200 sisi200 pau200 psi200 pp200 beamgas cosmic
• Event Generator Branch: evg
• Impact Parameter Level: central minb fixb
• Event Generator Level: hijing ven-4.12 vni-3.1 hijet
• Data Subset Level: set0001 set0002 ...
• Temporary duplicate file structures for: xdf txt

Take a few minutes to browse through these directories to become familiar with the menu of files that are available.

As you browse these directories note that you are only seeing the filenames, not the actual data files. The data are on tapes in the MDS silo. In order to get the tapes loaded into a drive and the files copied off onto disk please follow the next series of steps.

1. Open up a new window on a RCF interactive machine.
2. Change directories to the example below or to an event file of your own choosing:

   cd /star/mds/data/SD97/auau200/evg/central/vni-3.1/set0002/after/xdf

3. Examine the list of available event files by typing ls -l.
4. Request the data file to be copied from tape to disk by typing, for example:

   head vniafterauaurhic1_30.xdf

   If the requested data file has not been recently staged to disk this step may take several minutes, depending on how busy the tape drives are. When the file has been transfered to disk a message will be printed which lists the header structures for the xdf file. In the mean time, while this request is being taken care of, you may proceed to the next step.

5. Go back to your first window in the tut directory and make a softlink which will facilitate later access to the large data file that you are getting from tape. Type (all as one command without any returns):

   ln -s /star/mds/data/SD97/auau200/evg/central/vni-3.1/set0002

        /after/xdf/vniafterauaurhic1_30.xdf vniafterauaurhic1_30.xdf

   and verify that the softlink has been correctly made by typing ls -l.

Use STAF and PAW to examine the event generator files

In order to study and analyze event generator particle distributions it is most convenient to use PAW. Anyone knowledgeable with PAW can readily transfer the event generator text files to PAW ntuples and proceed with a standalone PAW analysis. Here we will see how to do this with much less effort by using the xdf files and STAF. At this point in the tutorials the beginner will probably not understand the details in the following steps which are STAF specific. What we will be doing is using a generic STAF executable to read the event generator xdf files into STAF datasets and tables, then translate these tables to PAW column-wise ntuples, and finally make some representative histograms. For STAF beginners, it is recommended that you just do the steps but try to understand what the end result is. After going through the later STAF tutorials, these steps should make a lot more sense. You should return to this exercise and be sure that each step is understandable. The method presented here is quite valid for analyzing STAR event files and is a worthwhile technique to learn.

If you have not yet run STAF or PAW from the RCF computers you will need to provide the necessary information to indicate the Internet address of your terminal, where you want the higz graphics window to be openned. To do this either (1) edit the higz_window.dat file in your home directory to direct output to your specific x-terminal's Internet address, or (2) create the higz_window.dat file with your own specific instance of the following example. This file only needs one line, for example:

0660 0000 0600 0600 xterm123.rhic.bnl.gov

will cause a nice size higz plotting window to appear in the upper right hand corner of the monitor screen. Be sure to substitute the correct Internet address for your local terminal in place of ``xterm123.rhic.bnl.gov.''

Start by typing the following STAF executable name:

tpcStaf

After the PAW banner appears, enter a ``1'' if you have created the higz_window.dat file with your terminal's Internet address on line ``1'' of that file. Next, execute the KUIP macro (kumac) file, test.kumac, in the /tut directory by typing

exec test 2

This causes the kumac file to execute and read the extant evgen.xdf file in your /tut directory into STAF tables, translate these tables to PAW ntuples, and make four plots corresponding to the second event in the file. This file corresponds to a Si+Si central collision VENUS event.

The kumac is reproduced HERE with explanation for each line. You may skip this for now but please return to this after completing the following STAF tutorials. After you have examined the event tables and histograms, end this STAF session by typing quit.

Hopefully, by now the requested file from the MDS tape robot has been loaded onto disk. If this is the case (i.e. you have the header information listed for the xdf file in the other window where you issued the request), then edit the test.kumac file and change the line

dio/newfile VENUS evgen.xdf r

which is the third line in the file, to

dio/newfile VENUS vniafterauaurhic1_30.xdf r

Start STAF again by typing tpcStaf, enter 1, then execute the modified kumac by entering

exec test n, where n=1,2... is the event number,

and examine the n-th event from the file that you retrieved from the MDS.

Running VENUS

In order to run VENUS, one executes a shell script which prepares the necessary input file for the program, directs the output file and runs the actual program. Most of the lines in this example script, auau_fght_minb, should not be changed by the casual user. However, several changes are straightforward. These are:

• In the script, auau_fght_minb, the line

  echo "2 1 -200. 79 197 79 197 6" >>$params_file

  makes 2 events for 200 GeV/c per nucleon of 79 charge 197 nucleons on 79 charge 197 nucleons. Change the 2; the 200.; the 79 charge and 197 A of the first; the 79 charge and 197 A of the second.

• In the script the line

  echo "'bmaxim' 14" >>$params_file

  the 14 is the maxium impact parameter in fm, thus it is min-bias. Change the impact for wanted collisions.

• In the script the line

  echo "'seedi' 6780735" >>$params_file

  is the random number seed. Change the seed to get a different set of events.

Leave everything else alone.

To execute the script and to run VENUS type:

csh auau_fght_minb

The output file, venus.gst, is in the preferred text format and may be easily viewed or edited.

To generate the STAF dataset and tables and to save the event file in xdf format, simply type:

gst2xdf

which will create a file evgen.xdf. Note that this will overwrite the evgen.xdf which you copied in at the beginning of this tutorial. If you want to keep the original, rename the file before typing gst2xdf. In UNIX, files can be renamed by typing the command

mv oldfile newfile

If you want to add particles or change the id of particles just edit the venus.gst file and run gst2xdf. Make sure you change the number of particles in the line of the file that starts with ``EVENT:.'' For example, if we add 10 particles and 1 vertex then the line in the file venus.gst would need to be changed from

EVENT: 1 1389 892 0.65619 2.5997

to

EVENT: 1 1399 893 0.65619 2.5997

where the added lines for the additional vertex and the last added particle are

VERTEX: -0.30510E-12 0.23817E-11 0.15143E-13 0.11859E-10 893 0 0 10

TRACK: 50 0.90958E-02 0.12198 0.11088E-01 1399 893 0 50

To examine this edited output file using STAF and PAW, run gst2xdf, edit the test.kumac to read in this new file if necessary, start STAF by typing tpcStaf and execute the kumac by typing `exec test n' as before.

At this point you have learned where many event generator files are stored, what sets of events are loaded in the MDS, how to retrieve the files onto disk for use in simulations, how to make histograms for the events, how to run VENUS, how to convert the text output into STAF dataset and table xdf representation, and how to edit or even create your own events and prepare them in xdf format for further simulations.

Other event generators are available such as Hijing, Fritiof and Vini. These are run by similar procedures but the input files are very different in each case. Please refer to the $STAR_REF/sim/fri/exa and $STAR_REF/sim/hij/exa for example scripts. Also refer to the following documents for:

FRITIOF

HIJING

VENUS

Detailed questions regarding STAR event generators should be forwarded to:

Ron Longacre