SBS Software

h1. Documentation of SBS-offline

{{toc}}

h2. Overview

This page is maintained by the UConn group (Eric Fuchey + Andrew Puckett) and as of February 14, 2020 is specific to the '''''master''''' branch of SBS-offline on github.

h2. Purpose

This page documents the SBS-offline program code, which purpose is to perform the data analysis for the upcoming SBS experiments.

h2. Getting the code and building the program

h3. Prerequisites

*Working [https://root.cern.ch/drupal/ ROOT] installation. '''libsbsdig is compatible with ROOT version 5 and ROOT version 6'''. '''''ROOT 6 is strongly recommended'''

*Working installation of cmake '''version 3.9 minimum'''

*Working analyzer '''built with cmake'''. for that purpose, refer to the instruction below.

h3. Instructions for analyzer cmake installation compatible

clone the analyzer repository from:

 * git clone git@github.com:JeffersonLab/analyzer.git

build it with cmake following the instructions at:

 * https://github.com/JeffersonLab/analyzer#compiling-with-cmake

_2 precisions:_ 

*it seems that in these instructions the "build" directory ''has to be'' in the analyzer directory.

*for your environment settings, in addition to the two lines mentionned in the instructions, you still want to define ANALYZER as the path to your install directory e.g.

 * setenv ANALYZER $HOME/local/analyzer

h3. Downloading the repository

h4. for simple users:

The code is hosted on a github repository owned by JLab. To clone via ssh (preferred method on JLab batch farm), do: 

bq. git clone git@github.com:JeffersonLab/SBS-offline.git

For this method to work, the ssh public key on the machine where you want to get the code must be added to your github account (see [https://help.github.com/articles/generating-ssh-keys/ Guide] to generating ssh keys and adding to your github.com account.)

Cloning the repository defaults to the "master" branch.

h4. for potential contributors:

* Have an individual github account.

* On github.com: Fork the JeffersonLab SBS-offline to your account. Setup to “watch” Jlab SBS-offline

* git clone git@github.com:GithubUserName/SBS-offline.git (This is ssh access). 

** This will be the “origin” remote repo in your local copy.

** Please do NOT make commits to the master branch.

** Create your own branch: git checkout –b NewBranchName

* git remote –add upstream git@github.com:JeffersonLab/SBS-offline.git

** This will be the “upstream” remote repo

* You can pull ( or fetch/merge) changes from the upstream (Jefferson Lab) repo.

* Always work in your own branch.

** You can push commits in your branch to the origin (Personal Github) repo

** You can ask others to pull down your branch into their code to test it out.

** Make pull request to JeffersonLab SBS-offline

* Once the pull request is accepted and put in the JeffersonLab master branch

** In your local repo, change to master branch.

** Pull the upstream master branch. ("git pull upstream master")

** Push the updated master to your origin repo: "git push origin master"

** If you have not done any your branch

*** Delete the branch "git branch -D MyBranchName"

*** Delete the branch on the your remote repo: " git push origin :MyBranchName"

*** Start a new branch

h3. Building and installing the library

Create a "build" directory that is parallel to the "SBS-offline" source directory (this is not strictly required, but the build directory must be separate from the "SBS-offline" directory in any case). 

You also need to have setup an installation path e.g. /path/to/sbs-offline-install

*NB*: similarly to the build directory, the /path/to/gsbs-offline-install directory shall '''not''' be the same as the source directory!

_The following instructions assume that "build" is parallel to "SBS-offline":_

If successful, the libsbs library and several other files and folders will be created in the "build" and the "install" directory.

To build and install, the procedure needs to be completed. From scratch:

bq. mkdir build

cd build

cmake -DCMAKE_INSTALL_PREFIX=/path/to/sbs-offline-install ../SBS-offline

make install

Then, the following line should be added in the OS login configuration file to take advantage of this functionality:

* source /path/to/sbs-offline-install/bin/sbsenv.sh (or source /path/to/g4sbs_install/bin/sbsenv.csh on the batch farm)

h2. How to use SBS-offline

A working example script using the SBS-offline library is available in the SBS-offline repository at the following path:

 * replay/replay_gmn.C

It is recommended prior to use it to source a short environment file to setup the database path correctly (and optionally the directory where to retrieve the data):

 * replay/setup_db.csh

It is preferable to not use them in this directory but copy them in another directory outside of your copy of the SBS-offline repository.

The script (and any other script using the SBS-offline library) uses the Hall A analyzer (Podd).

To execute this script:

bq. > analyzer

analyzer [0] .L replay_gmn.C

analyzer [1] replay_gmn_test("your_input_file_base", -1)

Note: doing ".L replay_gmn.C+" will not work unless a rootlogon.C file (attached to this page) is present in the directory you want to process your script in.

The first argument "your_input_file_base" is the base name of the input file minus the ".root" file suffix (i.e. the full file name would be "your_input_file_base.root"). 

The second argument is the number of arguments to process (-1 for all).

This will produce a file called "replayed_your_input_file_base.root" containing the information extracted from the analysis of the input file.