hperrey/adaqanalysis

ROOT-based program to analyze experimental (acquired with ADAQAcquisition) and simulated particle detector data

Accelerator-based In-situ Materials Surveillance

ADAQAnalysis

ADAQAnalysis is a program that provides comprehensive offline analysis of DAQ hardware settings and digitized detector data that are stored in the ADAQ file format (*.adaq.root) provided by the ADAQReadout library, which is part of the ADAQ libraries. The principal method for producing ADAQ files is through the use of ADAQAcquisition, a GUI-based program that provides complete DAQ capabilities and seamless production of ADAQ files for offline analysis. ADAQAnalysis is built on top of the ROOT data analysis framework. The program enables the user to completely inspect and operate on raw waveforms (view, baseline calculation, peak finding, pulse shape discriminate, etc), create and analyze pulse spectra (calibrate, background subtraction, peak finding, integration, etc), and to create publication quality graphics in vector (EPS, PDF) and raster (JPG, PNG) formats. Methods are provided to save all objects (waveforms, spectra, pulse shape discrimination histograms, etc) to either ROOT files, ASCII files, or CSV files for further analysis outside of ADAQAnalysis. The ability to analyze simulated detector data - using a Monte Carlo code like Geant4 - with the identical algorithms used on experimental data is provided by the ASIMReadout library, which is also part of the ADAQ libraries. This library manages readout and storage of simulated data into ASIM file format (*.asim.root). Finally, processing of waveforms can be performed in parallel using MPI to significantly reduce computation time on systems where multiple cores are available.

License and disclaimer

The ADAQAnalysis source code is licensed under the GNU General Public License v3.0. You have the right to modify and/or redistribute this source code under the terms specified in the license,

ADAQAnalysis is provided without any warranty nor guarantee of fitness for any particular purpose. The author(s) shall have no liability for direct, indirect, or other undesirable consequences of any character that may result from the use of this source code. This may include - but is not limited - to irrevocable changes to the user's firmware, software, hardware, or data. By your use of ADAQAnalysis, you implicitly agree to absolve the author(s) of any liability whatsoever. The reader is encouraged to consult the ADAQAnalysis User's Guide and is advised that the use of this source code is at his or her own risk.

A copy of the GNU General Public License v3.0 may be found within this repository at $ADAQACQUISITION/License.md or is available online at http://www.gnu.org/licenses.

Obtaining and building the code

First, a word on versioning of ADAQAnalysis. Git tags of the form X.Y.Z are used to indicate stable, production versions of the code that may be deployed with confidence for general use by the general user. A change in the X version number indicates a major release that departs substantially from the previous series, while a change in the Y version number indicates deployment of major new code features. A change in the Z number is used to indicate bug fixes and very minor changes to the codebase. Untagged commits are considered development versions of the code with no guarantee of stability and should only be used by developers in non-production situations.

To obtain ADAQAnalysis, you'll need to first clone the repository from GitHub and then switch to the appropriate git tag version before building the code.

  # Clone ADAQAnalysis source code from GitHub
  git clone https://github.com/zach-hartwig/ADAQAnalysis.git

  # Switch to a tagged production branch. For example:
  cd ADAQAnalysis
  git checkout -b 1.0.0-beta
  
  # To build the sequential binary locally
  make  

  # To build the parallel binary locally
  make par

  # To build both sequential and parallel binaries locally
  make both

To remove the transient build files and the ADAQAnalysis binaries, you can run:

  make clean  

Finally, add the following line to your .bashrc file to configure your environment correctly before running ADAQAnalysis:

    source /full/path/to/ADAQAnalysis/scripts/setup.sh >& /dev/null

Don't forget to open a new terminal for the settings to take effect!

Code dependencies

ADAQAnalysis depends on the following external codes and libraries. Note that all mandatory dependencies mustbe properly configured on the user's system prior to building ADAQAnalysis. Note that the use of Open MPI to enable parallel processing of waveforms with ADAQAnalysis is optional, as the code will compile successfully with or without parallelization.

1. GNU make : Mandatory

2. ROOT : Mandatory

3. ADAQ : Mandatory

4. Boost : Mandatory

5. Open MPI : Optional

Directory structure

The ADAQAnalysis directory structure and build system are pretty straightforward and easy to understand:

• bin/ : Contains final binary

• build/ : Contains transient build files

• doc/ : LaTeX code for the ADAQAnalysis User's Guide

• include/ : C++ header files, ROOT dictionary header file

• scripts/ : Collection of Bash utility scripts

• src/ : C++ source code

• test/ : ADAQ and ASIM files to used in development and testing (see below)

• Changelog.md : List of major content updates and fixes for each Formulary release

• License.md : Markdown version of the GNU GPL v3.0

• Makefile : GNU makefile for building ADAQAnalysis

• Readme.md : You're reading it

Test files

ADAQAnalysis includes (at present) three ADAQ-formatted files in the test/ directory that can be used with the program. The files are intended to be used to familiarize oneself with the various waveform analysis features of the program or to be used in the development and debugging of the code.

• NaIWaveforms_22Na.adaq.root : ~17 000 waveforms acquired with a 4"x4"x4" thallium-doped sodium iodide crystal coupled to a 2" photomultiplier tube. A sodium-22 source (0.511, 1.274 MeV gammas) was placed nearby. Intended for general program testing with a common, representative inorganic scintillator.

• EJ309Waveforms_Na22.adaq.root : ~31 000 waveforms acquired with a 2"x2" EJ309 liquid organic scintillator coupled to a 2" PMT. A sodium-22 check source (0.511, 1.274 MeV gammas) was placed nearby. Intended for general code testing with a common, representative liquid organic scintillator.

• EJ309Waveforms_AmBe.adaq.root : ~23 000 waveforms acquired with a 2"x2" EJ309 liquid organic scintillator coupled to a 2" PMT. An Americium-241/Beryllium-9 source (4.44 MeV gammas; 2-12 MeV neutrons) was placed nearby. Intended to be used for development of detector pulse-shape discrimination algorithms and features with liquid organic scintillators. Note that energy calibration for these waveforms may be obtained using the EJ309Waveforms_22Na.adaq.root data.

Contact

Zach Hartwig

Dept. of Nuclear Science and Engineering &
Plasma Science and Fusion Center
Massachusetts Institute of Technology

phone: [phone]
email: [email protected]
smail: 77 Massachusetts Ave, NW17-115, Cambridge MA 02139, USA