clas12-analysis

This is a generic analysis application for CLAS12 in groovy to read HIPO events selecting all unique final state particle combinations corresponding to a given topology, compute generic event-level kinematics commonly used for SIDIS analyses, and output the selected combinations and their respective kinematics to ROOT TNTuples.

The main purpose of this tool is to to compute event-level kinematics for all unique combinations of a given set of particles (e.g. proton pion pairs) without the hassle of rewriting your code and plugging in different configurations every time.

This tool only reads HIPO files (see CLAS12-Offline-Software) and outputs to ROOT files.

Dependencies

• CLAS12-Offline-Software
• CLASQADB
• J2ROOT

Containerized Installation

If you prefer to use a container, two examples are provided: a Dockerfile (docker/Dockerfile) and a Singularity/Apptainer definition (singularity/clas12-analysis.def). Below are minimal build and run examples that bind a host directory (for input and output) into the container so you can read/write data between the container and host.

Docker

Build the image from source:

git clone --recurse-submodules https://github.com/mfmceneaney/clas12-analysis.git
cd clas12-analysis
docker build -t clas12-analysis:latest -f docker/Dockerfile .

Or, pull a prebuilt image

docker pull docker://ghcr.io/mfmceneaney/clas12-analysis-docker:latest

Then, run the container and bind a host folder (e.g. /data) into /data in the container with the option -v <host_dir>:<container_dir>

docker run --rm -it -v /path/on/host:/data clas12-analysis:latest

You may run the project from the container like so:

docker run --rm -it -v /path/on/host:/data clas12-analysis:latest /usr/src/clas12-analysis/bin/run.sh --help

Apptainer/Singularity

Similarly, you may also use apptainer/singularity to build and run the container. Currently, apptainer and singularity have not diverged much and so they are interchangeable in the following commands. However, this is not guaranteed to last.

Build the image from source:

git clone --recurse-submodules https://github.com/mfmceneaney/clas12-analysis.git
cd clas12-analysis
apptainer build clas12-analysis.sif singularity/clas12-analysis.def

Or, pull a prebuilt image:

apptainer pull clas12-analysis.sif oras://ghcr.io/mfmceneaney/clas12-analysis-apptainer:latest

Then, run the project from the container and bind a host folder (e.g. /data) into /data in the container with the option -v <host_dir>:<container_dir>:

apptainer exec -B /path/on/host:/data clas12-analysis.sif /usr/src/clas12-analysis/bin/run.sh --help

Manual Installation

If you wish to install manually you will need the following tools

• jdk==21.0.8
• groovy==5.0.0
• scons>=4.8.1
• maven==3.9.9

On ifarm you may need to module load this java version. You may also need to update the library versions in gradle/libs.versions.toml and the java version in app/build.gradle.

Begin by cloning the repository and running the setup script

git clone --recurse-submodules https://github.com/mfmceneaney/clas12-analysis.git
cd clas12-analysis
bin/setup.sh

Then, source the environment script in your startup script:

pushd /path/to/clas12-analysis >> /dev/null
# cd j2root; source setup.csh; cd ..; #NOTE: Use this line for csh.
source env.sh #NOTE: Use this line for bash. 
popd >> /dev/null

Notes for installing on ifarm

Currently the default scons version 2.5 on ifarm does not support python 2.3, so just run the following before sourcing the setup script to get around this.

# For interactive use
alias scons "/usr/bin/env python2 `which scons`"

# For jobs
function scons {
    /usr/bin/env python2 `which scons`
}

Depending on what java version you have, in particular for java 8 on ifarm, you need to edit the setup script by commenting and uncommenting these two lines:

jar -c -f clasqa.jar clasqa/*.groovy # Comment this
# jar cf clasqa.jar clasqa/*.groovy  # Uncomment this

Finally, you might have to run the following so that gradle can SLURM jobs can read your gradle files:

chmod +r ~/.gradle/daemon/<version>/registry.bin

Setting your CLASSPATH

To set your $CLASSPATH manually add the following to your startup script (borrowed from bin/clara-shell script in $CLARA_HOME):

# set default classpath
if [ -z "${CLASSPATH}" ]; then
    CLASSPATH="${CLARA_HOME}/lib/*"

    # Add every plugin
    for plugin in "${plugins_dir}"/*/; do
        plugin=${plugin%*/}
        if [ "${plugin##*/}" = "clas12" ]; then # COAT has special needs
            CLASSPATH+=":${plugin}/lib/clas/*:${plugin}/lib/services/*"
        else
            CLASSPATH+=":${plugin}/services/*:${plugin}/lib/*"
        fi
    done

    CLASSPATH+=":${CLARA_HOME}/services/*"
    export CLASSPATH
fi

and run from $C12ANALYSIS/bin/run.sh.

If you already have J2ROOT and CLASQADB setup

Assuming your $CLASSPATH is configured correctly, you can proceed without further setup.

Getting Started

After installing the project, you should be able to run the application with $C12ANALYSIS/bin/run.sh which runs directly from java. Use the -h or --help option to see a detailed list of all available command line options and arguments.

As a legacy option, you may also run the application with $C12ANALYSIS/bin/an-groovy. However, you can run into thread permissions errors running gradle from this script in SLURM jobs so it is better to just set your $CLASSPATH manually and use $C12ANALYSIS/bin/run.sh instead.

Although this tool is primarily intended to have a generic application and primarily be used via execution of $C12ANALYSIS/bin/run.sh from the command line, you may also configure and run an analysis with more direct control over the configuration process by using a groovy script. See the examples folder for, well, examples!

Please note, the Constants and ExtendedConstants classes are not necessarily up to date, and you should also be especially careful to correctly set the beam energy and target mass.

Documentation

Check out our Read The Docs page for the full groovy docs!

Contact: matthew.mceneaney@duke.edu