PHENIX New User Tutorial

So, you're a new user to the PHENIX system, or you just have a burning desire to run some Muon code.
Whatever the case may be, the this tutorial assumes you're starting from scratch and covers how to get the code up and running, as well as the basics on how to work in the PHENIX enviornment.
A daunting task indeed, so let's begin.

The only prerequiste here is an RCF account, without which, you are completely and utterly useless. Fortunately, getting one only requires visiting here.

Time now to log in to RCF.  SSH is the client of choice, since usernames and passwords aren't transmitted in cleartext for the whole world to read.
Log in with the command :

> ssh -l [username] rcf.rhic.bnl.gov

For the rest of this tutorial, [username] refers to your user name on RCF typed without brackets. On your first time to log on to a machine using ssh, it will ask you if you want to add the machine to the list of known hosts, be sure to type yes. Additionally, if your username on RCF is the same as the machine you're on now, the -l [username] may be omitted. If you're having compatibility issues, add a -g.

Step 1 - Home Directory

source /opt/phenix/bin/phenix_setup.csh pro
setenv OBJY_LS_HOST phenixls.phenix.bnl.gov
setenv OO_FD_BOOT /phenix/data02/phnxreco/objy_try_cas/PHENIX_TRY_CAS
setenv OBJY_FDID 26727

[If you are unfamiliar with text editing in Unix, I suggest using Emacs (since vi is a tool of the devil) by typing emacs -nw .login.   The -nw parameter leaves emacs in text mode, otherwise it downloads the graphical version, which takes a few minutes. Make the changes and use control-x, control-s to save and control-x, control-c to quit.]

The first line runs a standard script which does most of the work in setting up your account. There are two versions of the libraries that this script can link to: pro and new. The new libraries are the latest and greatest, but they are also under development and therefore changing every day. The pro libraries are an older copy; a snapshot from a brief point in time when everything actually worked. The pro libraries give us a stable enviornment to use for the time being. Some day, the new libraries will be finished, but until then, it can save a few headaches to stick with pro. Meanwhile, the last three lines allow you to use a generic, test objectivity database that several macros reference.

Now add these lines to .cshrc :
setenv PH_HOME "/phenix/workarea/[username]/phool"

This line simply adds a shortcut to the software section of workarea which you can use in Unix commands. For example, change directories to your work area quickly you can use cd $PH_HOME (note the dollar sign) instead of typing out the path long hand.

Additionally, if you would like the prompt to show the current directory, which is useful while you are learning your way around, add this line:
set prompt = "%m:%~>"
 
 
 

Step 2 - Work Directory

To use CVS, first you must log in to AFS.  Then change to your workarea directory and check out the code. However, CVS will not work until the variable CVSROOT has been set to point to the CVS home directory (currently /afs/rhic/phenix/cvs). The phenix_setup.csh script which you just added to your .login file does this automatically, but it will not execute on its own until the next time you log in. So the first step is to manually run your .login, then log in to AFS, and finally check out the macros.

You should now have about 100 different Root macros in your offline/packages/gea/macros directory. To see what else is stored in CVS, you can either browse CVS on web here or poke around from the $CVSROOT directory.
Running these macros requires several input files and each macro produces even more output files. So, to keep the directory with the source code pristine (always a good idea), we will create a work directory to run them and copy the files we need there. Typing these long commands can be tedious, but to speed things up I suggest using lots of TAB completion (typing only part of the file or directory name and pressing tab) or copying and pasting directly from the commands-only version.
As far as creating a work directory goes, PHENIX is in a state of transition. In the past, certin constants and geometery data were stored in simple ASCII files and read in. In the future, all of these data will be stored in a central database. As for now, some macros use ASCII file, some use the database, and some use both. So for the time being, we will have to keep a supply of ASCII files on hand. Fortunately, there is a tool that handles it, the LuxorLinker. By sourcing the LuxorLinker in your work directory, you get a recent copy of data files to use.

> mkdir work
> cd work

Now call LuxorLinker

> source /afs/rhic/phenix/PHENIX_LIB/calibration/data/LuxorLinker

Steal some needed root files

> cp /phenix/workarea/pope/data/mu*.root .

Finally we need some input files.  Bear in mind that input files come in all shapes and sizes and can range from one to several million events.  The first input file is fairly good-sized (107 meg, 10% of your disk quota), so it would be better to create a link rather than actually copying it.

> ln -s /phenix/workarea/phnxreco/software/calibration/pisafile.dat.cZ .

One small file left

> cp /phenix/workarea/pope/CVSwork/offline/packages/bbc/wrk/root_macros/phnx.prdf .

Now that the work directory is set go, the only thing left to do is to set Root's macro path to point to the freshly checked out macros.  By doing this, it allows these macros to be run from any directory.
The first step is to copy root's initialization file into your home directory.

> cd ~
> cp /opt/phenix/root/tutorials/.rootrc .

Now edit the file and add the following to the unix MacroPath line:
Unix.*.Root.MacroPath:      .:$(ROOTSYS)/macros:$PH_HOME/offline/packages/gea/macros

Also, delete this line:
Unix.*.Root.DynamicPath:    .:$(ROOTSYS)/lib

By changing the .rootrc file, it is now possible to run the macros from any directory. This keeps your source directory free from tons of input and output files (which saves a lot of trouble if you ever have to check code back in) and gives you more flexibility. The dynamic path line is deleted as suggested by Kyle Pope (see here).
 
 

Step 3 - Running Macros

> source .rootrc
> ssh phnxmut
[username]@phnxmut's password:

To run the macros, change to the work directory and start up root (use the -b option to keep it in text mode, which runs much, much faster).
The most basic root commands are .x [macroname].C, and .q is to quit. Root has a tendancy to produce quite a lot of output, most of which scrolls past the buffer and is gone forever. To preserve the output for later enjoyment, calling root with root -b |& tee log saves the output in a file named log (this trick also works when using make). When running several macros in the same session, be aware that macros may call initialization routines which are only meant to be run once. If they are called twice in the same session, Root may or may not crash (for example, run mutResp.C and murecrun.C in the same session and look for 'Already Loaded' errors). Finally, Root comes with a few commands for debugging macros (not that you'll ever need them). One handy one is .T, the trace command, which outputs code as it's running; very useful for finding which line crashed.

> cd /phenix/workarea/[username]/work
> root -b
[0] .x mutResp.C
[1] .q

These macros take a few minutes each to run, and they produce tons of output.  Still, it should fairly obvious if a fatal error occurs and Root crashes in flames.  A word of advice should this happen: when Root crashes it generates a core dump for the debugger to read.  This isn't a problem in itself, however it is good to know that each core fire can be up to 270 megabytes.  Given that your disk quota is 1 GB, a few extraneous core files can be a problem. There are two good ways to get rid of core files. The first is to use a little search and destroy script by typing find . -name core -exec rm -v {} \; from your workarea. This removes all core files from the current directory and every subdirectory. A more elegant solution is to create a read-only file named core in every directory where you may be generating core dumps. Do this by typing touch core which creates an empty core file, then chmod 444 core which makes it read only. After exiting, you may wish to run murecrun.C to see even more Root in action.

Step 4 - Getting the Code

> cd ..            (This should bring you back to /phenix/workarea/[username]/ )
> mkdir source
> cd source
> cvs checkout -d mut offline/packages/mut

You will notice as the files are being checked out that you now have several hundred files in your source/mut directory.  This Muon Tracking package now needs to be built, which consists of compiling and linking every single file.  Additionally, building a package creates several hundred more files, and it finally produces a library directory that needs to be left alone.  When you consider that the /phenix/workarea disk (only 50 GB for around 500 users) hovers around 97% full, you see why building the package in your workarea may be a poor idea. Fortunately, we have access to several other large filesystems that are ideal for this purpose.  There are volumes from /phenix/data01 all the way through /phenix/data12.  Each one is a 400 GB RAID disk, so not only will it build faster, but we also won't have all of that wasted workarea space on our conscience.  For the purposes of this example we'll build on data01, though any of the 12 would work fine.

> mkdir -p /phenix/data01/[username]/install
> mkdir -p /phenix/data01/[username]/build/mut
> cd /phenix/data01/build/mut
> $PH_HOME/source/mut/autogen.sh --prefix=/phenix/data01/[username]/install
> make

Now, after you type make and press return, you really should stand up, use the restroom, get a can of Coke, take a leisurely stroll, etc. as it takes anywhere from 20-30 minutes to run.  The next one isn't nearly as bad.

> make install

Return to your home directory and edit the .login file so the newly installed libraries can be added to the search path. Add the line:
setenv LD_LIBRARY_PATH "/phenix/data01/[username]/install/lib:${LD_LIBRARY_PATH}"
(Note that you can check your library path, or any other enviornment variable, by typing echo $LD_LIBRARY_PATH)

Finally, run the macros again to check and see if they are using the libraries. Before they will use the new libraries, however, you either need to source .login again (so the new .login is executed) or simply type in that last setenv command.

> setenv LD_LIBRARY_PATH "/phenix/data01/[username]/install/lib:${LD_LIBRARY_PATH}"
> cd /phenix/workarea/[username]/work
> root -b
[0] .x murecrun.C
[1] .file
[2] .q

The .file command prints a list of all files that are currently opened by Root. In addition to all of the standard root libraries (/opt/phenix/root/lib and /afs/rhic/phenix/software/pro/lib) you should notice
two files listed from the install/lib path you just added.  This means that all is right with the world and PHENIX is smiling upon you.

I hope that this tutorial was as reasonably painless as it was informative. Please direct your comments, suggestions, or threats to miked@p25hp.lanl.gov
 
 
 

Here are a few other things you might find useful...
 

Visit some pages with excellent tutorials (i.e. better then this one) covering a vast range of topics.  Do yourself a favor and go to
http://www.rhic.bnl.gov/phenix/WWW/software/central/luxfaq.html
http://www.phenix.bnl.gov/phenix/WWW/offline/tutorials.html
http://www.phenix.bnl.gov/WWW/software/luxor/get_started.html

C.B.W.T.M.A? (Confused By Way Too Many Acronyms?) Check out the RHIC glossary
http://www-subatech.in2p3.fr/~photons/subatech/soft/phenix/doc/glossary.html

For a great overview of the PHENIX experiment and the simulation software read the PISA Primer Manual at
http://www.phenix.bnl.gov/WWW/simulation/primer4/seq_primer.html

This tutorial will quickly become obsolete, but there is one way to keep aprised of the lastest news and changes.  Visit
http://www.phenix.bnl.gov/phenix/WWW/p/subs/index.html  and subscribe to some mailing lists (login required).

Need a way to look a PHENIX source code?  Do it on the web from
http://www.phenix.bnl.gov/software/browsify

Looking for a database to practice on? Make your own at
http://www.phenix.bnl.gov/~messer/tutorials/pdbexplained.html
(Note: Before running the tutorial, you must checkout and make the framework/phool package)