Welcome to the Phobos Multiplicity Reconstruction Package How-To page
This note contains practical information for users of the Multiplicity reconstruction package. The official and authoritative guide to PhAT, the Phobos AnalysisTools, is here. If you need more detailed information about building and running Phat packages, look here for Multiplicity guides and here for general Phobos information.
It would be nice if you could just type phat and have it execute, but, because there is not now, and may never be, a Phobos standard for locations [directory paths] of needed files, you'll need to define the required environment variables PHATHOME and ROOTSYS differently for every site. By far the most common problem in getting phat to run is having incorrectly- or un-defined environment variables, which can lead to apparently bizarre error messages, such as one about the non-existence of a library that you can see is there. Try looking here to find out what's available at your site. At MIT, for instance, on ppcln.mit.edu, a possible set of definitions is
setenv PHATHOME ~verdier/Phat/CurrentVersion
setenv ROOTSYS /home/Root/root
After defining these required variables, you must define the derived variables
setenv LD_LIBRARY_PATH ${ROOTSYS}/lib:${PHATHOME}/lib/`uname`
setenv PATH ${PATH}:${ROOTSYS}/bin:{$PHATHOME}/bin/`uname`
These definitions can be made in a unix script. If you called this script, say, setphat, then to set the environment variables in most Unix systems you would type
source setphat
in the tcsh or csh shell or export setphat in the bash shell. If you're sure you'll always want them defined in this way, you can also put them in a login file such as ~/.cshrc, or add a line containing setphat to .cshrc.
If you're going to analyze data, you have to find it first. If you know the Phobos password, you can visit the Phobos site for the ever-changing official list of data files. Otherwise, you can just poke around starting from the top level of your disk; do
ls / or ls /mnt
and look for directories with phobos and/or data. Once you locate some data, you can define optional variables such as PHATDATA to simplify entering dataset names; at BNL,
setenv PHATDATA /phobos/u/phobos/PHOBOS_data/mdc2/root/full
Note: check this before trying to use it; it may no longer be valid!
To see if and how they're defined for you, type
env
or printenv PHATHOME (or any other environment variable).
The environment definitions and the location of data files are all you need to run the multiplicity reconstruction. You do NOT need to change to some other area(*), and, in fact, you should not do so because any files such as graphs and postscript that you leave in that area may be difficult to others to delete. It is often wise to cd to your own scratch area to avoid inadvertently deleting or overwriting other files.
(*) Unfortunately some of the files at BNL are not NFS-mounted and are only accessible to user 'phobreco' on certain computers. Ask Mark Baker or Don McLeod for the password if you need it.
You can run the reconstruction and look at numerical results without plotting anything; you can make make plots and save the results as PostScript or EPS without looking at them; but if you want to view graphs and histograms, you need to have the environment variable DISPLAY defined. Look here for information, particularly if you're trying to run at BNL, where the security restrictions may make this quite difficult, or, if you're not running ssh, impossible.
You can check whether you have the correct environment variables set with the aid of a ROOT macro, or script, called checkmul.C, that is distributed with the standard Phat package. You can execute it by typing
phat $PHATHOME/phatmul/macros/checkmul.C
This will analyze a sample two-event file that is part of the distribution. It should print a line that tells how well the reconstructed multiplicity agreed with the generated value, and also show a small plot. If you don't have an X-client running, add -b after phat to run in batch mode with no plot. If something is wrong at this point, you'll have to find out what it is before continuing.
The easiest way to reconstruct the multiplicity for a set of events is also to run a ROOT macro. The standard one for multiplicity is called runmul.C, and you can run it by executing
phat $PHATHOME/phatmul/macros/runmul.C
and answering the questions, the most important of which is what datafile to use. Go back to How To Get Started to find out what files are available at the site on which you're running. Although runmul.C seems long-winded, you will find if you scan it that almost all the complexity is in the dialogue that specifies files and processing options, and in making the script flexible enough so that it's easy to change; the actual reconstruction, once everything is set up, is invoked by the single statement mp.Process(ev).
Here are the questions you must answer. Simply pressing return will give you the indicated default value for each option.
1. Enter h for a brief help note, cr to bypass it:
Entering h will display a brief paragraph. It should open a VMS-like hierarchical help menu, and this is planned for completion about one month after Phobos is decommisioned. If you really want help, you do what the ROOT team does: go and read the lucid and informative comments that the code writers have included in their code. Right.
2. Enter name of root- or apx-format DST file, space for none,
or
1 or cr = /mnt/data04/phobos/pre-mdc2-2/hijing_c.root,
...
There should at this point be an additional dialogue that allows you to look around for data; but at present you have to have figured it out earlier. Sorry. You CAN just analyze the standard 2-event file, in $PHATHOME/data/hijing_2cen.adat.root; this is one of the options offered in the dialogue. Note that this file uses the 'new' set of names; see Q. 6.
3. File type (0 = .root, 1 = .apx, 2 = user-created .root? [cr = 0]):
This is an option to try to use some older files that are not converted to .root format. Don't try it unless you absolutely have to, and then don't try it.
4. Use MC information if present (n | y)? [cr = y]:
Until we have real data, y is a good option. It includes the 'truth' data taken from the MC tracks and hits, along with doing the reconstruction. The alternative at present is to use the HitArrays prepared by standard Phat methods, without reference to the MC information. Of course, it's the same information. Well, almost. There are small differences, a fraction of a hit, believed to come from tracks that barely tipped the edge of a sensor.
5. Use standard vertex finder (y | n)? [cr = y]:
Yes. This option is only present in case TPhVertex is broken, or for testing the effect of inserting a wrong vertex. If you say no, it will ask you where the vertex should be.
6. Use current [0] or pre 30-Dec-98 [1] array names [cr = 0]:
This should be 0, but if the name of the MC hits objects is suddenly changed from "MCHits" to "PMCHits", as recently happened, you won't be able to analyze the event. Runmul tries to help, but all it can tell is if there are any of the standard-named objects, and warns you if it finds none. If ROOT is still viable after you crash, try typing ev->ls() and see if you can make sense of it; but this may just crash worse.
7. Number of events to process (cr = all):
It takes several seconds to read (depending on where the data file is) and about 2 seconds to reconstruct each event. The name of the file usually indicates how many events are there. It's a good idea to do one or two just to see if the data are valid, before trying a bigger job.
8. Number of events to skip initially (cr = 0):
Use this for analyzing a file in segments.
9. Setup script filename (cr for none, 1 = $PHATHOME/phatmul/macros/setmul.C):
This file allows you to change reconstruction parameters after startup (so the geometry is already loaded) but before any actual multiplicity reconstruction. You might use this, for example, to change the energy deposition or secondary fraction parameters as described below.
10. Output script filename (cr for none, 1 = $PHATHOME/phatmul/macros/writemul.C):
You can write objects called MapSets, containing all the data and reconstruction results, which can be used later to make plots and to re-reconstruct the data. But normally you wouldn't do that. If you do, note that a typical event uses 1 MB compressed and 3 MB uncompressed, and there's no warning before you fill the disk.
The analysis starts now, and you'll get more or less indication of the progress depending on the local variable ReportLevel, which you can set by copying runmul.C to your own area, and editing it (if it says 'permission denied' you'll have to do chmod +w runmul.C first). If you're doing this, you might as well also change the names of the data files to those accessible from your work area.
There are lots of ways to simplify these commands; I prefer to define environment variables in the same way as PHATHOME; for example
setenv mm $PHATHOME/phatmul/macros
setenv md $PHATHOME/data
so
phat $mm/runmul.C
would execute the reconstruction, and you would specify $md/hijing_2cen.adat.root for the data file; but there are some strong advocates of putting the simplifying definitions in hidden files, perhaps on the grounds that ignorance is bliss.
Once the runmul macro has completed, you can make graphs and histograms of the results. Here's an example and a list of past plots, in various formats. Look here for more information.
Almost all the data you'll want to access are contained in objects that we call maps, or, formally, 'instances of objects of class TPhPadMap'. A map is a 3-d array of floating point numbers. Two of the dimensions are spatial, typically the Z-XY and azimuthal phi (in degrees, just like Geant) coordinates for sensors and eta and phi for the physics displays. The third dimension indexes over a set of variables. We use two sets of maps, one for physical sensors, in Z-XY space, the other for physics variables, in eta-phi space. In the multiplicity package, we call the physical sensor maps 'SensMaps' and the physics maps 'Displays'. Variables in a SensMap include the calibrated energy deposited in each pad, the number of Monte Carlo primary and total tracks that hit that pad, and the energy deposited by primary tracks. There are presently 28 variables in a Display, starting with the dEtadPhi for the cell and including all the reconstruction results. To see what they are, type
mp.GetDisplay(0)->Print()
The names are self-explanatory, almost. We will often refer to the integrated dN/dEta and its error by variable indices 13 and 14, respectively, in examples; but these numbers are not magic and are expected to change when we move into the world of MapSets. We originally planned to use enumerated values for these variables, but difficulties with the CInt ROOT interpreter made that infeasible.
Assuming as usual that the TPhMul instance mp contains data from analyzing one or more events, you can type
$PHATHOME/phatmul/macros/plotmul.C
and follow the prompts to see an example of a standard set of plots. Sorry, there's no hyperlink because there's no standard installation of Phat.
Plots are created by methods of the maps; the recommended way is to access them through methods of TPhMul. To plot dN/dEta, for example, you can type
d1 = mp.GetGraph ("d1", "*+in", 13, 14, 360)
d1->Draw ("ape")
The first statement asks the multiplicity processor to return in d1 a pointer to a ROOT TGraphErrors object containing dNch/dEta. The arbitrary name "d1" is necessary for ROOT to identify the new object. "*+in" is the name of a particular display, which happens to have all active sensors in Phobos. The '*' is actually used by mp to select the sensors that are to be included; the '+in' is simply a mnemonic tag for us to remember that it's to be integratd on phi. To find out what displays are available, do
mp.ListDisplays()
The indices 13 and 14 define the variables we want to plot, 13 for dN/dEta and 14 for the RMS error assigned to it; see the discussion of maps above.
You can get a formatted dump of the actual values using the TPhPadMap::Print method with a range of variables (recall that no arguments gave you a list of variables); for example, to show dN/dEta and its RMS error, type
mp.GetDisplay("*+in")->Print(13,14)
For a 2-d histogram of the truncated and normalized (to normal incidence) energy deposited in all the sensors whose names begin with 'MO', do
d2 = mp.GetHist("d2", "MO*", 11)
d2->Draw("lego2")
To see the energy deposited in a group of sensors, do
d3 = mp.GetHist("s1", "MOB*", 0)
d3->Draw("lego2")
Here the ROOT name, "s1", is used also by GetHist to determine what kind of map you want; if the first character is 's' or 'S', it's a sensor map. You could avoid that restriction by using the bizarre call
d3=mp.GetSensMap(0)->GetHist(mp.GetSensMaps(),mp.GetSensDefs()->GetNDefsAct(),"xx","MOB*",-1,0)
Don't practice typing this, because it will soon be replaced by a sensible call to a method of the TPhMapSet class.
Note that these plots are conspicuously lacking in things like axis labels, legends, and time stamps. The class TPhMulDisp, used in plotmul.C, was created to try to bring the fundamental ROOT plot objects up to some semblance of publication quality. This struggle is ongoing.
You can get formatted printouts of the plotted data by loading macros:
.L $PHATHOME/phatmul/macros/printgraph.C
printgraph(d1)
will display in concise format the contents of TGraphErrors *d1, and similarly printhist.C for any TH2F.
You can save your current display canvas in files with formats such as PostScript, EPS, and GIF by using
gPad->Print("name.ext")
where ext is 'ps' or 'eps'. The GIF format must, and the others can, be created using the File menu at the top of the display.
Do
mp.GetDisplay("*+in")->Print()
to see a list of all the variables, and
mp.GetDisplay("*+in")->Print(2,5)
to make a formatted display of the values for each bin of variable #2, or Edep, the total energy deposited in this bin; #3, or E1, the sum of parameterized single-track energies entered in this bin, #4, or nTracks, the reconstructed total number of tracks, and #5, or nTracksLim, the reconstructed total number of tracks with large energy depositions truncated to the canonical 500 keV.
The simplest statistic is the integral of the any variable in a map. Type
mp.GetDisplay("*+in")->GetIntegral(13,14)
to see the integral of d2N/dEta/dPhi, which is the reconstructed total charged multiplicity. GetIntegral(23,24) will give you the same quantity for the generated tracks. For a good reconstruction, these should agree. mp.GetDisplay("V*")->GetIntegral(13,14) would give you the same quantity for the vertex detector system.
These are special cases of a more general statistics facility:
Float_t stats[20];
mp.GetDisplay("*+in")->GetStats(13, 14, 20, stats)
returns an array of no more than 20 statistical variables (at present only 14 are calculated). For a formatted listing, do
mp.GetDisplay ("*+in")->PrintStats (13, 14)
Note: these statistics have a questionable meaning when carried out over sparsely binned data, since there's no way for the integrator to know whether an empty bin means there were no hits in that bin, or simply that no measurement was made in that bin. The integration method is being modified to handle this problem better; but this is physics, not mathematics. It would be unwise to hardwire any locations in the statistics array into code.
To see the bin size of a display, use
mp.GetDisplay("MPA*")->GetSize(ixy)
where ixy = 0 for the Eta-bin and 1 for the Phi-bin. To change it, use
mp.GetDisplay("MPA*")->SetSize(ixy, newValue)
Similarly, you can use GetNCells, SetNCells, GetMin, and SetMin for any display or sensor map. For example, you could use
TPhPadMap *d1 = mp.GetDisplay("MOF*")
d1->SetSize(0, d1->GetNCells(0) * d1)->GetSize(0))
d1->SetNCells(0, 1)
d1->SetSize(1, d1->GetNCells(1) * d1)->GetSize(1))
d1->SetNCells(1, 1)
to save time during production running by reducing this display to a single bin.
Changing display or sensor maps, as with changing energy deposition or secondary fraction parameters, is best tried out interactively, as in the examples above, and then entered into a setup macro executed after the mp.Process(ev,-1) call that is the initialization phase of TPhMul.
There are two kinds of parameters that control the reconstruction. One is the set of values of the average energy deposited per track; the other is the set of Total tracks / primary tracks. These are initialized and controlled by the classes TPhDept and TPhFsec, respectively, and may be accessed by the Get and Set methods of these classes. The syntax is intentionally somewhat ugly to discourage random uninformed changes. For example,
mp.GetDeptP(0)->SetPar(27, 4, 144.0e-6)
would reset the average energy deposited per track for sensor MOA3 at eta = -0.4 to 144 keV. The phatmul macro setmul.C shows how this should be done in a systematic programmatic way during the the initialization phase of TPhMul. Similar considerations apply to the secondary fraction values.
MapSets, or instances of TPhMapSet, are arrays of TPhPadMaps treated as an aggregate. They make operations that involve more than one map, such as selecting a number of maps to be combined in a plot, or reading / writing a set of maps, much simpler. You can't actually use them, yet. Well, you can create them on disk and then read them back; but you can't reanalyze the data with different parameters. Maybe by next week you'll be able to do that, too, and then this section will have more information.
The current projects are integrating the TPhMapSet class into the fabric of TPhMul (Verdier), tuning the parameters for different generators (Reuter), generalizing the statistical properties of the maps (Verdier), factorial moment analysis (Wosiek), analyzing test beam data to get tuning parameters for Geant simulations (Pernegger), and wavelet analysis (Baker). If YOUR name is not on this list but you would like it to be, or if there are sins or omission or commission here, please let me know.
30-Oct-1998: Problem with hit iterators corrected; tuned for new geometry..
30-Dec-1997: The multiplicity package produces sensible distributions.
Last edited: Monday, February 22, 1999 11:59:16 AM by Robin Verdier [verdier@mit.edu]
