Beamline Calibration How-To

This is a step-by-step outline of how to perform the beamline calibrations. Results from each year of running can be found in the child page links below.

Decide upon usable triggers.

Preferrably minbias triggers, though some special triggers are fine too. The point is that the trigger should not have a bias on the reconstructed primary vertex positions (an event-wise bias is acceptable, as long as the average over many events yields no overall bias). A trigger that selectively prefers events at, for example, positive z versus negative z, is not a bias which concerns us. Meanwhile, a trigger which selects triggers using tracks from only one patch in phi in the TPC may indeed bias the vertex-finding because of track energy loss, or SpaceCharge, or other distortions.
Deciding upon these triggers may involve making a few calibration passes on a subset of the data with enough statistics to see different biases. So if there is any uncertainty about the triggers to use, there may be some iteration of the following steps.
There is also a triggers webpage which provides helpul information about the various triggers (NOTE: its URL changes for each year, so try similar URLs or parent directories for different years).

 

Decide upon filetype to use.

If there are files already available with all the other calibrations (TPC alignment, T0, drift velocity, twist, etc.) in place, then one can process data faster by using either event.root (fast) or MuDst.root (really fast) files. As of this writing, one can process either of these using the FindVtxSeeds.C macro:

   void FindVtxSeeds(const Int_t   mode=0,
           const Int_t   nevents=10,
           const Char_t  *path="/star/data13/reco/dev/2001/10/",
           const Char_t  *file="st_physics_2304060_raw_0303.event.root",
           const Char_t* outDir="./");

where mode is unused, and the other parameters are self-explanatory. In this case, output files go to the outDir. The output files will be discussed later.

If no available DST files will suffice, then the DAQ files will need to be processed using BFC options. Through 2004, it was only necessary to put "VtxSeedCal" as the single chain option to accomplish this. As of this writing, the 2005 data requires the chain: "MuDST VtxSeedCal -OBmap OBmap2D fcf". For 2006 (and hopefully beyond), a more generic option has been created called "VtxSeedCalG". The user's chain must specify the year-specific options. For 2006, we are trying "VtxSeedCalG,B2006a,ITTF,VFMinuit". The output files will, by default, go into either the local directory, or ./StarDb/Calibrations/rhic/ if it exists.

 

Choosing the actual files to use.

Now it is time to query the database for the files to use. My approach has been to link several DB tables which provide a lot of information about fill numbers, triggers, numbers of events, etc, in an effort to somewhat randomly choose files such approximately 10,000 useful triggers are processed from each fill. To do this, I passed this query to mysql via the command:

   cat query.txt | mysql -h onldb.starp.bnl.gov --port=3501 -C RunLog > output.txt

where the query file must be customized to select the unbiased triggers, triggersetups, and runs/fills. This should return something like 10,000 events per run accepted by the query. The macro StRoot/macros/calib/TrimBeamLineFiles.C can be used to pare this down to a reasonable number of events per fill (see the macro for more detailed instructions on its use). This macro's output list of files then can be processed using the chain or macro as described above.

 

The output of the first pass.

The output of the VtxSeedCal chain or FindVtxSeeds.C macro consists of anywhere from zero to two files. The first, and most likely, file will be something like: vertexseedhist.20050525.075625.ROOT. (I do not at this point remember why the output uses capital .ROOT in the filename.) This file will appear if at least one usable vertex was found, and it contains an ntuple of information about the usable vertices. The timedate stamp will be that of the first event in the file, minus a few seconds to insure its validity for the first event in the file. The second possible file will be of the form vertexSeed.20050524.211007.C and contains the results of the beamline fit, which is performed only if at least 100 usable vertices are found. These table files are only useful as a form of quick QA, but are not needed for the next step.

 

The second (aggregation) pass.

All the desired ntuple files from the first pass should be placed in one directory. I usually fill a directory with soft links to the ntuple files I want to use, where I give the soft links a lower case .root extension instead of the upper case (Root won't open .ROOT files). It is then a simple chore of running the macro:

   Int_t AggregateVtxSeed(char* dir=0);

where dir is the name of the directory with the ntuple files. The output of this pass will be just like that of the first pass, but will reduce to one file per fill. Again, no ntuple file without at least one usable vertex, and no table file without at least 100 usable vertices. These output table files are what go into the DB after they have been QA'ed.

 

QA the tables.

I like to look at the table values as a function of time graphically to do QA. I do this by putting everything into one text table in a single file that I can import into Excel (or any other graphing program) by executing this shell script, which takes the tables in a local StarDb/Calibrations/rhic/ and puts output text files in a local txt/ subdirectory. Here are some example slopes and intercepts from my first look at QA on 2005 data:

One can see several outliers in the data in addition to the normal trends of machine operations. Many of these outliers are due to limited statistics for a fill. Care must be used in deciding what to do:

• If the statistics are great for that fill, this may be a real one-fill alteration of beam operations by RHIC, and the datapoint should be kept.
• If there is a long gap in data before that point, then it may be wise to keep the datapoint.
• If statistics are poor (usually the case with about 1000 or fewer usable vertices from a fill), and the data on either side of the point appears stable, it is probably a good idea to remove the datapoint.
• It may be possible to run some additional files from that fill to increase the statistics to the level where the datapoint is more significant.

Once these decisions have been made, and any additional data has been processed and iterated, the QA should eventually come to a point subjectively deemed satisfactory. Shown here are the finalized values for 2005:

 

Enter the tables into the DB.

Put all the table files into one directory from which you will upload them to the DB. I use ~genevb/public/vertexSeed as that directory in the example below. Log in as the stardb user via ssh onllinux6.starp.bnl.gov -l stardb (you will need the password) and then cut and paste the following:

cd macros/vertex
stardev  
setenv STDB_SERVERS $STAR/StDb/servers/dbServers_robinson.xml
./fileTimes.pl -f vertexSeed -d ~genevb/public/vertexSeed
root4star -b 'WriteTables.C("Calibrations_rhic","vertexSeed")'

Log out when finished.

 

...and you are done.

G. Van Buren