Quick Start

#Introduction Here you will find information on how to quickly start using this software. We will be working under the assumption that you have no desire to know the inner workings of the code, but simply want to get some graphs to look at. This guide has the following assumptions:

• You will be using ROOT
• You will use high resolution timing algorithms.
• Your experiment is of a simple ToF measurement with two detectors a start and a VANDLE.

These assumptions will be valid for a majority of the experiments that are being performed as of this writing. If you do not require these features, then you should remove any of the associated high resolution timing analyzers from the configuration file.

#Prerequisites

• HRIBF/ORNL Libraries
• GNU Scientific Library - Requires v1.13 or older

#Additional Recommended Programs

• [ROOT] (https://root.cern.ch/)

#Obtaining the Source Code You should obtain the most recent version of the software via git:

git clone https://github.com/pixie16/pixie_scan.git

If you want to contribute to the software you should fork to your own github account, and then create merge requests. Please bear in mind that you are expected to conform to the Style Guidelines.

#Setting up your Experiment Processor Before building or compiling you should setup your experiment processor. As an example, take a look at the Template experiment processor header and source.

See the separate page on creating an Experiment Processor on how to fully setup this processor.

#Building See the Cmake-Guide for instructions on how to build the software.

#Compiling Once cmake has finished you are now ready to build and install the software.

make install

You can always assign make to use more cores if your computer has them. This can significantly speed up the compilation process.

##Prepare Configuration File The software is primarily controlled via an XML configuration file. For a complete overview of the configuration, see the page XML Config

NOTE: This file is read at runtime, you do not have to recompile when you make changes here!!

###Detector Driver The node DetectorDriver holds the various Processors and Analyzers that you are going to be using for the analysis. For our simple example we will be wanting the following pieces:

<Processor name="BetaScintProcessor"/>
<Processor name="VandleProcessor" types="small" res="2" offset="200"/>
<Processor name="NewExperimentProcessor"/>
<Analyzer name="WaveformAnalyzer"/>
<Analyzer name="FittingAnalyzer"/>

The two processor lines define the classes that will handle the manipulation of the data to measure our ToF. The analyzers, work specifically on the traces, and these two will provide the high resolution timing. There are some of the processors that take arguments into their constructors (Ge, Vandle), information on these arguments can be found in the pages for the respective class.

In some analysis, you do not need to define multiple processors to handle information. For example, the VandleProcessor does not need the Beta or Double Beta processors defined in order to perform time-of-flight calculations. This is because these processors pull the necessary detector summaries themselves and build the required information. In these scenarios, you may simply define the VandleProcessor, unless you require histograms built in the Beta or Double Beta processors.

###Map The Map node tells the program what type of detector is plugged into a given Module/Channel combination. We have moved to this scheme since we now define both the energy calibration and walk calibration at this point. The tags for a channel are now defined as a comma separated list inside the "tags" key. Below is the sample code for our current example:

###TimeCalibration We are now ready to input the timing calibrations. These calibrations are used to align the gamma prompts for the ToF measurement. In addition, this section defines the physical position of the bar relative to the initial position of the measured particle (gamma, neutron, etc.). This calibration differs from the previous one, as it is done on a bar-by-bar basis and not per channel.

If you do not include a calibration for a channel into this node, the program will provide a default calibration of 0.0 for all offsets. In addition, any of the offsets that are left out of the correction, for example if you did not measure an "xoffset", it will automatically be set to zero. This removes the necessity for the declaration of all of the detectors in the analysis.

Finally, the program now recognizes more than two start detectors. This is done through a list of "tofoffsets". Please refer to the sample code below, as well as, the sample configuration: config/Config.xml.example. The "loc" field in the start nodes denote the location of the starts. In the event that the start is a bar style detector, this will refer to the bar number. For a detailed description of these variables refer to Time Calibrations and VANDLE Setup.

Inside the TimeCalibration node we will have the following code:

You will find a detailed description of these variables in the Time Calibrations and VANDLE Setup section.

###Physical

The Timing node contains all of the information necessary for the successful extraction of the high resolution timing from a trace. It defines things such as the trace length and delay, the ranges for the waveform, and the fitting parameters for various detectors. The most important things to update in this section are the TraceDelay and TraceLength. Please note the units that are in each of the parameters.

###Fitting

###Trace

###TreeCorrelator We will not be using the TreeCorrelator for this example. You can remove all contents of this node. However, please leave the node definition. Refer to Tree Correlator for more info on how to setup this node appropriately.

###NoteBook Finally, you can change the output information from the notebook if you'd like. This is not a critical step.

##Retrieving Information from the Event After an event has been created it is sent for processing. The first step of processing is to calibrate the individual channels and summarize the information contained in the event. For each detector type that is present in the event an object called DetectorSummary is created. This object holds detector related information such as the energy, timestamp, and the multiplicity of the detector among other things. For example, the following command will retrieve energy of the scint in the event. double energy = revt.GetSummary("beta_scint:beta")->GetList().begin()->GetEnergy(); where revt is the name of the variable holding the raw event information and energy will contain the energy of the scintillator.

To retrieve the multiplicity associated with VANDLE ends use the following command: int vmult = revt.GetSummary("vandle")->GetMult(); The reference manual can provide a list of all commands to retrieve information from the detector_summary or the rawevent.

##Plotting All plotting is controlled through the "plot" function defined in DeclareHistogram. This function is a C++ wrapper that has been placed around the DAMM count1cc and set2cc subroutines. This allows for the code to be easily changed between damm and ROOT histograms. For those using DAMM to view the output of the analysis all plots are created in the "drrsub.f" file located in the scan directory.

In order to plot into a histogram one must first define it in the DeclarePlots method of the experiment Processor. In addition, each Processor has a specific range of DAMM IDs that it is allowed to use. This is defined in the DammPlotIds.hpp. To define a 1D and a 2D histogram, you must first define the variables for the histogram numbers:

namespace dammIds {
    namespace experiment {
        const int D_ENERGY_BETA = 0;
        const int DD_ENERGY_TIME = 1;
        const int DD_BETA_TRACE = 2;
    }
}

This is generally found near the top of the '.cpp' file of interest. For the BetaScintProcessor, this will create histograms with IDs 2050, 2051, and 2052. We can now define the histograms themselves in the DeclarePlots method.

DeclareHistogram1D(D_ENERGY_BETA, SA, SA, "Beta Energy");
DeclareHistogram2D(D_ENERGY_BETA, SA, SA, "Beta Energy vs Time");
DeclareHistogram2D(D_ENERGY_BETA, SA, SA, "Beta Traces");

To plot a one dimensional histogram of energies: plot(D_ENERGY_BETA,energy); You can send any type of numerical value to the plot function. The variable is rounded into an integer before being passed to the DAMM plotting functions. A two dimensional histogram is plotted with the command plot(DD_ENERGY_TIME,energy, time); and a three dimensional histogram (plotting a trace for example) uses the command plot(DD_BETATRACE, xval, row, traceval);

##Program Execution After the compilation has completed successfully the executable pixie_ldf_c will be present. Run the pixie_ldf_c program as you would any other program: ./pixie_ldf_c hisname Where "hisname" is the name of the damm histogram that will be created. At the scanor prompt load in the appropriate ldf file as follows SCANOR->file tutorial/tutorial.ldf Next start the analysis with the following command SCANOR->go After starting a variety of output should be printed to the screen. The first lists all the detectors that are being used in the analysis. This includes information about what is happening at various stages of the code, the status of reading in the configuration, and the creation of the detector summaries. After completion of the analysis, end the SCANOR program SCANOR->end You are now ready to take a look at your output in DAMM. This concludes the main part of the tutorial.

##Summary This should complete the basics on how to setup and run the code. There are a variety of histograms predefined in the Processors. Remember, under the new framework, you do not have to recompile when you are switching out Processors. Changes to the source code (new histograms, gates, etc.) necessitate compilation.