ADAQAnalysis

Overview

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 the Geant4 Monte Carlo code 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/thread 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.9.0
  
  # To build the sequential binary locally (required)
  make 

  # To build the parallel binary locally (optional)
  make par

  # To build both sequential and parallel binaries locally (optional)
  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/ : final binary

• build/ : transient build files

• 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_{Cs137,Na22}_1300V.adaq.root : Waveforms acquired with a 2"x2" EJ309 liquid organic scintillator coupled to a 2" PMT. Voltage was -1300V. A cesium-137 (0.662 MeV gammas) and a sodium-22 (0.511, 1.274 MeV gammas) were placed nearby for each file. Intended for general code testing with a common, representative liquid organic scintillator, and, in particular, electron (gamma) calibration.

• EJ309Waveforms_AmBe_1300V.adaq.root : Waveforms acquired with a 2"x2" EJ309 liquid organic scintillator coupled to a 2" PMT. Voltage was -1300V. 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_{Cs137,Na22}_1300V.adaq.root files.

• NaIPMT_Cs137.asim.root : Simulated data using Geant4 and ADAQ's ASIM library for a 2"(diam)x2" NaI cylinder. Data stored in the file at present is the energy deposited per event, the number of scintillation photons produced in each event, and the number of scintillation photons detected in each event. Intended primarily for development of the ASIM plotting and analysis features of ADAQAnalysis and comparison to experimental data.

• EJ301_{Cs137,Na22}.asim.root : Simulated data using Geant4 and ADAQ's ASIM library for a 2"(diam)x2" EJ301 cylinder. Intended for ASIM feature development and simulating calibration of EJ301 detectors.

• EJ301_Neutrons_{2.45,14.1}MeV.asim.root : Simulated data using Geant4 and ADAQ's ASIM library for a 2"(diam)x2" EJ301 cylinder. High precision (HP) neutron transport physics (e.g. cross section data driven) was used for maximum fidelity. Intended for ASIM feature development.

Contact

Zach Hartwig

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

phone: +1 617 253 5471
email: [email protected]
smail: 77 Massachusetts Ave, NW17-213, Cambridge MA 02139, USA
web : https://www.psfc.mit.edu/people/faculty/zachary-hartwig