README.md

# Exercise 1: running a simple SHMS replay

*Skills: Hall c analyzer, git, ifarm*

Note: This tutorial assumes you are logged in on the JLab interactive farm.

## Step 0: Load the PolHe3 software environment

```bash
source /group/c-polhe3/software/setup.sh
```

## Step 1: setup your own copy of the Hall C replay
* Start of by creating your own directory on our group disk (if you haven't already)
```bash
mkdir -p /group/c-polhe3/Users/$USER
```
* You will also need a personal directory on the volatile disk
```bash
mkdir -p /volatile/hallc/c-polhe3/$USER
```
* Next, go into your personal directory on the group disk
```bash
cd /group/c-polhe3/Users/$USER
```
* And make a clone of the official Pol He3 Hall C replay directory
```bash
git clone https://eicweb.phy.anl.gov/jlab/hallc/exp/polhe3/hallc_replay.git
```
* Now, you will have a new directory that contains the replay scripts

* Now, go into this directory and look around
```bash
cd hallc_replay
ls
```

## Step 2: setup the input and output directories
You will need to link the location of your raw input files, 
as well as for your output replay files in the replay directory. The Hall C
replay uses these links to locate the input files and write the output files.

* The input files for this tutorial are located on the volatile
```bash
ls /volatile/hallc/c-polhe3/example_files/raw
```
* First create a symbolic link to this location (from within your replay directory)
```bash
ln -s /volatile/hallc/c-polhe3/example_files/raw raw
```
* Secondly, create a personal output replay directory, a subdirectory of your personal volatile
```bash
mkdir -p /volatile/hallc/c-polhe3/$USER/example_output
```
* Thirdly, make a symlink to this location (again from within your replay directory)
```bash
ln -s /volatile/hallc/c-polhe3/$USER/example_output ROOTfiles
```
*Note that the names of these symlinks has to be `raw` for input files and `ROOTfiles` for your output files*

## Step 3: Run the SHMS replay for 5k events
*At the start of this step you should be in your personal replay directory, and you should have loaded the PolHe3 software setup script*

* The replay launcher scripts are located in the SCRIPTS subdirectory.
```bash
ls SCRIPTS/*.sh
```
* To display the usage of the replay script, you can use the help flag `-h`:
```bash
./SCRIPTS/hcreplay -h
```
* The relevant flags in this case are `-r` for the run number, and `-n` for the number of events to analyze.
* To see which run numbers are available, you can list the files in the `raw` subdirectory from step 2:
```bash
ls raw/
```
* There are two SHMS runs available, and one HMS run.
* The 4-digit number that is part of the file name is the run number you need.
* **Remember the lowest SHMS run number in the output files**.
* For the rest of this exercise, replace XXXX in the commands with this number. **Else nothing will work**
* For this exercise, we want to analyze only the first 5k events
* Now you should be ready to run the replay (again, replace XXXX with the run number)
```bash
./SCRIPTS/hcreplay SHMS -r XXXX -n 5000
```
* *NOTE: if this is the first ever time you run this, this will fail. This is normal (related with a bug in root)*
* So if this happens, repeat the step again. It should work now.

* The analyzer `hcana` should print a lot of output, and this will take a few minutes to run
* You should now have the root output file, as well as several report files and logs:
```bash
## output files are located under ROOTfiles:
ls ROOTfiles/

## report files are located under REPORT_OUTPUT/PRODUCTION:
ls REPORT_OUTPUT/PRODUCTION

## log files are located under: logs
ls logs/
```
*If you run into issues in this step, please contact Sylvester on the Hall C Slack (hallc.slack.com), and attach a copy of the files in the logs directory.*

## Step 4: Investigate the replay output

The last part of this exercise has you count the number of electrons in your sample in a quick-and-dirty analysis.

* Go into your output directory and open the output file you generated in root (replace XXXX again with your run number):
```bash
cd ROOTfiles
root shms_replay_production_0XXXX_5000.root
```
* *Note: this will display some warnings about missing TClass dictionaries. This is normal, and you can ignore it.*
* Do a rough count of the number of electrons. We can do this the quick-and-dirty way using the root builtin tree::Draw functionality:
```bash
T->Draw("", "P.cal.etottracknorm > 0.8 && P.cal.etottracknorm < 2 && P.ngcer.npeSum > .5 && P.gtr.dp > -10 && P.gtr.dp < 24")
```
* This command will print out a number as `(long long) YYY`
* **This number YYY is the "solution" to this exercise. If you like you can contact Sylvester on the Hall C Slack (hallc.slack.com) to check your answer.**.
* Note that the (very rough) cut we do for good electrons in this example is the following:
    * Calorimeter E/P larger than 0.8 (most energy deposited in Calorimeter, electrons undergo an electromagnetic shower in the calorimeter and therefore leave behind more energy than pions.)
    * Calorimeter E/P smaller than 2 (remove unreasonable values)
    * Number of photo-electrons in the Noble Gas Cherenkov larger than 0.5 (Electrons emit Cherenkov radiation in the Noble Gas Cherenkov with N2 at this energy, pions don't.)
    * dp between -10% and 24%: Only use particles with a momentum fraction that is in the region where we understand the spectrometer optics
    * *In principle we should also make sure the particle comes from the target, but for this exercise this is unnecessary.*
* *Contact Sylvester on the Hall C Slack (hallc.slack.com) if you encounter any issues, or have any questions.*