Getting started

Installation

The following steps will build Cicada from scratch. Starting with a terminal window …

1. Clone the repository and make a build directory as recommended above. You will also have to initialize the submodules.

git clone "https://github.com/project8/cicada"
cd cicada
git submodule update --init --recursive
mkdir build

2. To configure the installation you can use cmake, ccmake, or cmake-gui. For a first configuration, using either ccmake or cmake-gui is highly recommended. The following instructions are for ccmake, but the steps with cmake-gui would be approximately the same.

cd build
ccmake ..

You will be prompted to press [c] to configure, and the window will fill up with several options. You should set the CMake variable CMAKE_BUILD_TYPE to either RELEASE, STANDARD, or DEBUG (default), in order of how much text output you would like (from least to most) and how much compiler optimization should be performed (from most to least). The install prefix is specified by the CMake variable CMAKE_INSTALL_PREFIX. The library, binaries, and header files will be installed in the lib, bin, and include subdirectories. The default install prefix is the build directory. After you’ve finished, if you’ve changed anything press [c] again to configure. Then [g] to generate and exit.

3. Build and install.

make install

Or if you want to take advantage of parallel building to get things done faster:

make -j install

If the compiler runs into errors during the build, first check that you’ve updated the submodules and that you have all of the required dependencies installed (many are called “optional” on this page, but if you want to build without them you must also specify this in the cmake window). If you made a change to the dependencies or submodules, you may have to wipe the build directory and start again from step 1; simply writing make install again will not always work.

4. Use this_cicada.sh to set your PYTHONPATH and ROOT_INCLUDE_PATH:

source /path/to/cicada/install/bin/this_cicada.sh

This will allow you to access the Python and ROOT interfaces and the python example scripts coming with cicada.

5. Developpers: Add the installation folder (where the bin and lib have been installed) path to your paths.

export PATH=/path/to/cicada/install/bin:$PATH
export LD_LIBRARY_PATH=/path/to/cicada/install/lib:$LD_LIBRARY_PATH

How to use

Cicada does not do anything per se, but is a library retaining the structure of some objects generated by Katydid (see Objects’ structure and description section for more details). An example on how to read a Katydid object is present in Library/python. The core of this scripts is:

import CicadaPy
CicadaPy.loadLibraries()

import ROOT.Katydid as KT
from ROOT import TFile, TTreeReader, TTreeReaderValue

def ReadKTOutputFile(filename,var):
    # Change to point to the ROOT file you want
    # filename = "../../scripts/PhaseI_analysis_roofit/events_000001097_katydid_v2.7.0_concat.root"
    file = TFile.Open(filename)
    if not file:
        raise FileNotFoundError("File {} does not exist".format(filename))

    # Extract tree from file
    tree = file.Get("multiTrackEvents")
    # Create TTreeReader
    treeReader = TTreeReader(tree)
    # Create object TMultiTrackEventData to "point" to the object "Event" in the tree
    multiTrackEventObject = TTreeReaderValue(KT.TMultiTrackEventData)(treeReader, "Event")

    resultList = []
    # Go through the events
    while treeReader.Next():
        exec("resultList.append(multiTrackEvents.Get{}())\n".format(var))
        print(resultList[-1])
    return resultList

1. The first two lines add the Cicada libraries into the ROOT module, so they can be imported by the second import. Note that here we call ROOT.Katydid and not ROOT.Cicada: we are using the Katydid namespace that was added to ROOT. One day once the Cicada library will be used as a dependency of Katydid, we will use ROOT.Cicada.

2. The function ReadKTOutputFile takes a file name and a variable of interest and it will print the value of this variable. To do this, it extracts the tree called multiTrackEvents containing the TMultiTrackEventData object and makes use of the ROOT TTreeReader to get each value of this object. The iterator of the tree reader is then used to append to a list and print the value of the parameters var of the event object using a GetX method (defined by the class). The list is then returned.