Table of Contents
- Introduction
- How to configure and install cnipol
- How to run cnipol
- How to produce summary plots
- General Description of Directory Layout
- Automating the Process
- Alpha Calibration File
- General remarks
cnipol is a software package designed to acquire and analyze data from the Relativistic Heavy Ion Collider (RHIC) polarimeters at the Brookhaven National Lab (BNL). The first objective of this package is usually referred to as the "online" layer and designed to support the data acquisition and to provide a quick feedback by carrying out a fast online analysis. The second objective is to execute a more rigorous "offline" data analysis and present the results in a systematic way. It is normally referred to as the "offline" layer of cnipol.
There is a wiki page with some details about the RHIC polarimetry:
https://wiki.bnl.gov/rhicspin/Polarimetry
The results obtained with cnipol can be found at
http://www.phy.bnl.gov/cnipol/
The development of cnipol is done using the git version control system. Good manuals can be found at:
- https://git-scm.com/book/en/v2 - somewhat in-depth
- https://help.github.com — github specifics
The best way to start with the analysis is to clone the latest version of the code from the git repository. From the location where the package will be installed on your machine issue a following command:
git clone https://github.com/rhicspin/cnipol.git
cd cnipol
This will create a cnipol directory with your local cnipol repository.
In order to sync your changes in your local copy with the central repository you will need to have have them commited to your local repository first. To do that you need to first "stage" them using
git add -p
This will interactively ask you which changes you want to stage. If there are new files that you would like to add to the repository use
git add path/to/new/file
To check what changes are staged use git status and git diff --staged.
To unstage all of the changes use git reset.
After staging the changes use git commit -m "your commit message here" to turn them into a commit. Use git log -p to see list of local commits.
The newly created commit will only exist in your local repository. To synchronize with the common repository issue:
git pull --rebase
git push
Later should ask for your github credentials. If you plan to push oftenб it is a good idea to generate an ssh key and add it to gihub: https://help.github.com/articles/connecting-to-github-with-ssh/
It is important to sync your changes in a timely manner. Letting your changes pile locally for too long increases chance of having a merge conflict.
The analysis framework depends on a few external libraries and programs including
- ROOT5
- MySQL
- sqlite3
- boost (through opencdev)
These (except ROOT) are typically readily available on most linux systems.
Before the code can be compiled and executed a number of environment variables
must be set. We provide an example bash script script/setup.sh with predefined
paths which should work on the eic cluster of the RACF (RHIC and ATLAS Computing
Facility). Review and modify this script as needed to match your specific system
configuration. An example is the variable CNIPOL_DIR, which the directory you setup the code. This script can be ran with an optional argument for the RHIC run
number, e.g. run_id = 9|11|12|13|15|17, execute in the terminal (Note: You need to be in a bash shell. Type bash):
source script/setup.sh [run_id]
Once the environment variables are set the cnipol package can be built in $CNIPOL_DIR as:
mkdir build
cd build
cmake28 .. -DCMAKE_BUILD_TYPE=RelWithDebInfo
make
The compiled executables should appear in this build directory along
with the cnipol libraries.
Make sure the following environment variables are set to valid locations before running the cnipol executables
$CNIPOL_DATA_DIR
$CNIPOL_RESULTS_DIR
asym accepts a number of options which can be listed by running it with a -h
option. Here we just give a few most common examples used to process regular and
calibration data.
To analyze a regular data file simply do in the build directory:
./asym -r <meas_id>
where <meas_id> is a unique name of a measurement, e.g. 12345.001. Note that
usually <file_name> = <meas_id>.data. The program searches for the input
<file_name> file in $CNIPOL_DATA_DIR and creates an output directory <meas_id>
in $CNIPOL_RESULTS_DIR. Typically, the output directory contains a ROOT file
with a predefined set of histograms, a log file (stdoe.log) with the entire
output of the program, a PHP file with information about the measurement and
results to display on the web, and a file with calibration results.
To analyze an alpha or pulser measurement use the --alpha option:
./asym --alpha -r <meas_id>
Once in a while, when, for example, the cnipol code is modified one may need
to re-analyze a large number of data files. This can be achieved in several ways
by utilizing common linux tools. Here for completeness we provide a simple shell
script that takes a text file containing a list of measurements (one <meas_id>
per line) as a single argument and starts a certain number of parallel jobs in
the background. The scripts for energy calibration and regular runs can be
executed respectively as:
script/run_asym_alpha.sh <meas_list>
script/run_asym.sh <meas_list>
Before you begin you should source the setup file as decribed above.
Often it is useful to see how polarization or other observables change from
measurement to measurement during some period of time. To study such time
dependence we developed masym, a program that runs on a set of measurements
analyzed with asym. The output ROOT files produced by asym are used as input
to masym. Executing the following command will create a <meas_list> directory
in $CNIPOL_RESULTS_DIR with a ROOT file containing summary histograms:
./masym -m <meas_list>
Here <meas_list> is a plain text file with a list of measurements to process.
This file is assumed to exist in $CNIPOL_RESULTS_DIR/runXX/lists/ and to have
one <meas_id> per line.
Optionally, the analyzer can provide a plain text file
$CNIPOL_RESULTS_DIR/runXX/hjet_pol with H-Jet polarization values.
Information from these text files will be
used by masym in the summary plots.
Similarly to masym, we provide a program to study time dependences in a set of
alpha-calibration measurements. This program is called malpha and can be
invoked as:
./malpha -m <meas_list> -o <output_file>
where <meas_list> is a file in $CNIPOL_RESULTS_DIR/runXX/lists/ with a list
of unique names corresponding to measurements recorded by the polarimeters when
no beam was present in the RHIC.
$CNIPOL_DATA_DIR— directory containing raw input data files that are read byasym. Typically points to/eicdata/eic0005/run??/datawhere??is the run number.$CNIPOL_RESULTS_DIR— output directory for asym (it creates$CNIPOL_RESULTS_DIR/<meas_id>subdirectories). Also input and output directory for masym (it reads asym output and produces its output in$CNIPOL_RESULTS_DIR/<meas_list>). Typically points to/eicdata/eic0005/run??/root.- Another input directory for masym is
/eicdata/eic0005/runXX(literallyXX) that is a local git repository clone of https://github.com/rhicspin/runXX. It contains plain text files with lists of measurements, target statuses and H-Jet polarizations. I also contains text cdev logs, but these are not used anymore. Due to some bug masym will look for it in$CNIPOL_RESULTS_DIR/runXX, which we working around by creating a symlink likeln -s /eicdata/eic0005/runXX /eicdata/eic0005/run17/root/runXX.
First, you need to follow the link below to set up a tunnel to the blue and yellow pC machines at IP 12. This will provide you with a tunnel into the machines without requiring a password.
https://wiki.bnl.gov/rhicspin/Automated_pC_setup
The name of the script to execute is run_asym_daemon.sh. However, the first line in the script should be changed to the location of the setup.sh and the run number.
After the tunnel has been established you can start the automated process by executing the following command:
nohup ./run_asym_daemon.sh > some_output_file_name
and you can put an ampersand at the end of the process if you want to hide it. The ampersand will allow you to continue working in your current terminal. Regardless, the process will be running and looking for new files every 60 seconds.
There are currently two interfaces to query Gpm log data (such as bias currents, beam luminosities, ags polarization measurements):
SshLogReader(with caching optionally provided byCachingLogReaderwrapper)opencdev::LocalLogReader
The first one requires starting a new ssh connection to a machine in the CAD network to run exportLoggerData for each query. This method is generally slow and it is not working reliably with large volumes of parallel queries (which you get when you have multiple instances of asym running). The second method is fast and doesn't require tunnel at runtime, but it needs a full copy of the data available locally (on disk at path defined by $SLOW_CONTROL_LOG_DIR environment variable). There is a small script (cdev_export.py) to maintain such a copy.
To have get it working you will need freetds and python-sybase libraries installed first:
wget http://mirrors.ibiblio.org/freetds/stable/freetds-0.91.tar.gz
tar zxf freetds-0.91.tar.gz
pushd freetds-0.91
./configure --prefix=$HOME/local && make && make install
popd
wget --no-check-certificate https://sourceforge.net/projects/python-sybase/files/python-sybase/python-sybase-0.40pre2/python-sybase-0.40pre2.tar.gz
tar zxf python-sybase-0.40pre2.tar.gz
pushd python-sybase-0.40pre2
mkdir -p $HOME/local/lib64/python2.6/site-packages/
SYBASE=$HOME/local CFLAGS="-DHAVE_FREETDS -UWANT_BULKCOPY" PYTHONPATH=$PYTHONPATH:$HOME/local/lib64/python2.6/site-packages python setup.py install --prefix=$HOME/local
popd
You also need to get most recent version of opencdev:
git clone https://github.com/rhicspin/opencdev.git
The tool needs a connection to the database:
ssh yellowpc -L 5000:acnlinbd:5000 -Nf
Environment variables need to be setup to point to the libraries:
export SYBASE=$HOME/local
export PYTHONPATH=$PYTHONPATH:$HOME/local/lib64/python2.6/site-packages
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HOME/local/lib
The script is ran as:
opencdev/tools/cdev_export.py
It should iteratively download Gpm index database from remote Sybase server and save the contents into ./sql directory. The sql files should be rendered to local Sqlite database using find sql -exec cat {} \; | sqlite db.sqlite command. Then raw SDDS files with the data itself are downloaded to ./run_fyXX directory. Both db.sqlite and data files need to go into the directory pointed by $SLOW_CONTROL_LOG_DIR.
During the course of the run, a long alpha measurment should occur and create the alpha calibration files needed for properly processing the measurments. Once this file is created you will need to edit the following code to include the file name of the alpha calibration. You can find the code at the following:
/contrib/RunPeriod.inc
Make sure to change the start_time, the polarimeter_id, the alpha_calib_run_name, and possibly the gain_slope (may not need to include the gain_slope at all). The other parameters are the default tdc and adc cuts on the bananas plots.
The code for the analysis of the RHIC polarimeters data has changed significantly starting 2010. Nevertheless, one may still find it useful to look through the older documentation which can be found at
http://www4.rcf.bnl.gov/~cnipol/Analysis/pC/index.html
Different people have been working on analysing polarimetry data. Some notable packages used for this purpose are:
| ags_cni |
Code for AGS data analysis. AGS has a jet polarimeter much like the one at RHIC. Analysis code has branched a long time ago and is now supported by CAD. |
|---|---|
| hjet-analysis |
Code for the H-jet polarimeter data analysis Supported by the RHIC Spin group and provides the official polarization numbers. |
| new hjet analysis |
An analysis by Andrei Poblaguev that pioneered support of the new JLAB fADC250 VME DAQ system. |