(From contributions by Craig Tull, Claude Pruneau and Ken Wilson)
In this tutorial you will learn the following:
Environment
We assume here that you have access to the RHIC AFS cell and the STAR directories and files mounted thereon. As always, you must get an AFS token with the klog command before accessing any AFS area. We also assume that the correct CERNLIB and STAR_SYS_LEVEL values have been correctly set to 96a and SL97b, respectively. Check that your PATH variable is set correctly with the Unix command:
which tpcStaf97b
You should see a response similar to:
/afs/rhic/star/arch/irix/bin/tpcStaf97b
where irix should be replaced by the appropriate architecture name. This is a realistic STAF executable for TPC simulation and tracking which we will use later in these tutorials. If you do not see the proper response, check that you do indeed have an AFS token (type tokens) and rehash.
Setup Workspace
Setup a work space under your home directory where you can work through the STAF tutorials safely. Use the following Unix commands:
cd ~
mkdir STAF_Tutorial
cd STAF_Tutorial
When you are finished with the STAF tutorials, you can remove all remants with the following Unix commands:
cd ~
rm -r STAF_Tutorial
Create Work Directory and Run STAF
From the STAF_Tutorial directory create a test package called tut and work sub-directory called wrk by typing:
mkdir tut
cd tut
mkdir wrk
Then change directory to wrk and start STAF by typing tpcStaf97b or in general:
cd ~/STAF_Tutorial/tut/wrk
tpcStaf97b
Enter a ``1'' at the prompt if you have a higz_window.dat file defined as in the preceding event generator tutorial. In the following examples only the STAF commands will be shown, the first two Unix commands are implied.
N.B. It is assumed that the user is familiar with the KUIP interface from CERN. An introduction and/or overview of KUIP is beyond the scope of these tutorials. Please see the KUIP User Manual for details.
Basic STAF Commands
This tutorial will introduce you to the most commonly used STAF commands in SL97b. You should just type them in for now. If you run into problems, exit STAF and start again. After you have started STAF, enter the commands in typewriter font listed below. Note that the STAF executable tpcStaf97b is for doing realistic TPC simulations and tracking and hence contains many tables. For now just ignore these and only pay attention to the tables created and filled in the following steps.
Creating tables:
Show what table types exist:
tdm/types/list
Show what table instances exist:
tdm/list
Create the table type ``track,'' and create an instance of that type called ``svt_track'' with a maximum of 3 rows:
tdm/newtable svt_track 'struct track { long id; float p[3];} ; ' 3
Please pay close attention to the spaces, for example between ' and 3. Look for the ``track'' table type you created:
tdm/types/list
Look for ``svt_track'' you created as an instance of the ``track'' table type:
tdm/list
Check that the ``svt_track'' is really an instance of the ``track'' table type:
tdm/table/typename svt_track
Show the definition of the ``svt_track'' table:
tdm/table/show svt_track
Check to see how long the table can be:
tdm/table/maxrowcount svt_track
Change it to hold up to 10 tracks (rows):
tdm/table/maxrowcount svt_track 10
Check to see how long the table can be now:
tdm/table/maxrowcount svt_track
Make a new instance of the ``track'' table type called ``tpc_track'' with a maximum of 10 rows:
tdm/newtable tpc_track track 10
List the tables and you will see your new one:
tdm/list
Delete the new table:
rm /dui/tpc_trackPutting data in tables:
Check to see how many actual tracks the table holds:
tdm/table/rowcount svt_track
Make it hold 1 track:
tdm/table/rowcount svt_track 1
Put in some data for the track:
tdm/table/cell/putvalue 'svt_track[0].id' 1
tdm/table/cell/putvalue 'svt_track[0].p' 0.2 0.3 0.4
Get the numerical values out of the table:
tdm/table/cell/getvalue 'svt_track[0].id'
tdm/table/cell/getvalue 'svt_track[0].p'
Type out a kumac file which puts 10 entries in the ``svt_track'' table:
shell more /star/u2/ray/WWW/staf_tut/svt_track_fill.kumac
Execute this kumac file which fills 10 rows in the ``svt_track'' table:
exe /star/u2/ray/WWW/staf_tut/svt_track_fill.kumac
Print out the data in the table:
tdm/table/print svt_trackCopying tables to ntuples:
Copy ``svt_track'' to an ntuple with ID=1:
tnt/newcwn 1 svt_track
Check that you created an ntuple:
nt/list
Check that the ntuple is also a soc object:
soc/list
Print out the data in the ntuple:
nt/scan 1
Delete the ntuple and its soc entry:
hist/del 1
soc/deleteobject tntCWNtuple1
Joining tables:
The table join operation begins by first sorting the tables to be joined according to a specified variable in the table, and then joining the 2 or more tables for all linked rows and putting the results into a third table. The user must first specify the sorting variables and the join procedure before executing the sort and join commands. The following example should make this clear.
Fill table ``svt_track'' with nontrivial values in ``random'' order:
exe /star/u2/ray/WWW/staf_tut/svt_track_fill2.kumac
Print the table variables:
tdm/table/print svt_track
Create a new table type called ``track2'' and an instance of it called ``emc_track'':
tdm/newtable emc_track 'struct track2 { long id; float energy;} ; ' 10
Fill table ``emc_track'' with nontrivial values in ``random'' order:
exe /star/u2/ray/WWW/staf_tut/emc_track_fill2.kumac
Print the table variables:
tdm/table/print emc_track
Create a table sorting object called `idsort' which will sort any table according to the variable `id':
top/newsort idsort id
Apply this sorting object to the above tables:
top/sort_agent/sort idsort svt_track
top/sort_agent/sort idsort emc_track
Verify that the table rows have been rearranged in increasing numerical order for the variable `id' in both tables:
tdm/table/print svt_track
tdm/table/print emc_track
Create a table joining object called `idjoin.' List the variables in the tables to be joined which are to be included in the resulting new table and the names you want to call these old variables in the new table. Put this information in the first set of curly braces as shown below. Finally, list the variables in the two tables to use in the join procedure, in the second set of curly braces. (Note: the ``_'' at the end of the following lines indicates a continuation of a command line in KUIP).
top/newjoin idjoin '{svt_track.id idj,_
svt_track.p pj, emc_track.energy EJ}'_
'{svt_track.id emc_track.id}'
Join the tables ``svt_track'' and ``emc_track'' as specified in the `idjoin' object and put the results into a newly defined table called ``combination'':
top/join_agent/fastjoin idjoin svt_track emc_track combination
Look at the joined table ``combination'':
tdm/table/print combination
and verify the table joining action.
Reading and Writing data:
From the STAF prompt create a subdirectory:
mkdir test
See if the subdirectory is there:
ls
See what is in the subdirectory:
ls test
Create a table in the subdirectory:
tdm/newtable test/tof_track track 1
See if it is there:
ls test
Put some data in the new table:
tdm/table/rowcount test/tof_track 1
tdm/table/cell/putvalue 'test/tof_track[0].id' 1
tdm/table/cell/putvalue 'test/tof_track[0].p' 0.2 0.3 0.4
Go to the new directory:
cd test
Create a new file stream for writing data:
dio/newfilestream output myfile.xdf W
Write out the test directory and its tables as one event:
dio/stream/putevent output
Write out four events with actual data:
dio/stream/putevent output
dio/stream/putevent output
dio/stream/putevent output
dio/stream/putevent output
Close the filestream:
dio/stream/close output
Go back to main directory:
cd /dui
Make a new subdirectory:
mkdir incomming
Go to new subdirectory:
cd incomming
Create a new file stream for reading data:
dio/newfilestream input myfile.xdf R
Read in the test directory and its tables as one event:
dio/stream/getevent input
List the incoming data:
ls
ls test
Read the all the data to the end of the file:
dio/stream/getevent input
dio/stream/getevent input
dio/stream/getevent input
dio/stream/getevent input
When you have finished exercising the STAF commands quit STAF by typing:
quit
and verify that the file ``myfile.xdf'' exists in your /wrk directory.