MEGAlib - The Medium Energy Gamma-ray Astronomy software library

What is MEGAlib?

The Medium Energy Gamma-ray Astronomy library (MEGAlib) is a set of software tools which are designed to simulate and analyze data of gamma-ray detectors, with a specialization on Compton telescopes. While MEGAlib was originally developed for astrophysics, it has been expanded and extensively used for ground based applications such as nuclear threat detection applications. The library comprises all necessary data analysis steps from simulation/measurements via event reconstruction to image reconstruction.

MEGAlib contains a geometry and detector description tool for the detailed modeling of different detector types and characteristics, and provides an easy to use simulation program based on Geant4. For different Compton telescope detector types (electron tracking, multiple Compton or time of flight based) specialized Compton event reconstruction algorithms are implemented in different approaches (Chi-square and Bayesian). The high level data analysis tools allow to calculate response matrices, perform image deconvolution (specialized in list-mode-likelihood-based Compton image reconstruction), determine detector resolutions and sensitivities, retrieve spectra, determine polarization modulations, etc.

The highly modular and completely object-oriented library is written in C++ and utilizes ROOT and Geant4. While it has been originally developed for the Compton scattering and pair creation telscope MEGA, it also has been successfully applied to a wide variety of hard X-ray/gamma-ray telescopes in space and on ground, such as COMPTEL, NCT, ACT, NuSTAR, GRI, GRIPS, and HEMI.

For a general overview consider reading "MEGAlib - Medium Energy Gamma-ray Astronomy Library", or "MEGAlib - Simulation and Data Analysis for Low-to-medium-energy Gamma-ray Telescopes". For details about the algorithms refer to Andreas Zoglauer, "First Light for the Next Generation of Compton and Pair Telescopes" and Florian Schopper, "Entwicklung eines Teleskops zur Abbildung von Gammastrahlung mittels Comptonstoss und Paarerzeugung". For a detailed insight into simulations with Cosima see "Cosima - the Cosmic Simulator of MEGAlib"

Moreover, you might want to take a look at the following posters: "MEGAlib - Simulation and Data Analysis for Low-to-medium-energy Gamma-ray Telescopes", "Geomega: MEGAlib's geometry and detector description tool for Geant3, MGGPOD, and Geant4" and "Realta: MEGAlib's real-time analyzer for gamma-ray detectors".

Key programs and features

Geomega

Geomega - Geometry for MEGAlib - is MEGAlib's universal geometry and detector library. The geometry itself is described in an object oriented ASCII file, which describes the volume tree, the materials, the detectors, the trigger criteria, etc. Geomega is used by all other programs of MEGAlib including the Geant4 simulator Cosima.

Geomega's key features are:

• Advanced geometry file format with features such as constants, math functions, for-loops, if conditions, matrices, etc.
• Various detector types: simple single volume detectors, strip detectors, voxel detectors, MEGA-like calorimeters, Anger-cameras, etc.
• Interactive display of the geometry using ROOT's standard or openGL display
• Overlap checking based on Geant4's overlap checker
• A sophisticated detector effects engine including energy, position, time resolutions, noise and trigger thresholds, ADC overflows, etc.
• Complex trigger criteria: by detector type or by individual detector, trigger or veto, by channel or by detector

For a full list of features see the Geomega manual. The latest version can be found in the doc-directory of MEGAlib.

The main reference for Geomega is: A. Zoglauer et al., Cosima - The cosmic simulator of MEGAlib, NSS Conference record, 2009

Cosima

The "Cosmic simulator" Cosima is MEGAlib's Geant4 based simulator. It utilizes the geometry and detector information from Geomega to perform the simulations. The beam and spectral parameters include options for astrophysics and as well as for most terrestrial applications ranging from homeland security to phantoms for medical imaging. The output is a simple text file which can be analyzed by the other MEGAlib programs.

For a full list of features see the Cosima manual. The latest version can be found in the doc-directory of MEGAlib.

The main reference for Cosima is: A. Zoglauer et al., Cosima - The cosmic simulator of MEGAlib, NSS Conference record, 2009

Revan

Revan - the real event analyzer - is responsible for reconstructing events in MEGAlib, and can handle simple, single site events, Compton scatter events, pair creation events, and high-energy charged particle events such as muons. However, Revan's specialization is Compton event reconstruction and therefore it contains a variety of different algorithms to determine the event type, starting with coincidence search, charged particle track searches including Compton electron tracks, and several algorithms to determine the Compton interaction sequence (classic and Bayesian algorithms).

Revan can handle simulated as well as real measured data!

The main reference for Revan is: Andreas Zoglauer, "First Light for the Next Generation of Compton and Pair Telescopes", Doctoral thesis, TU Muenchen, 2005

Mimrec

Mimrec is MEGAlib's high-level data analyzer. It contains options to perform event selections on all important event parameters of single site, Compton and pair creation events (e.g. energies, interaction distances, scatter or opening angles, and many more). It's main goal however is to perform list-mode likelihood image reconstruction in spherical, Galactic, as well as Cartesian coordinates (2D, 3D) including different response calculation approaches (from quick and dirty to slow and sophisticated) which are mostly optimized for Compton image reconstruction. Finally Mimrec contains several options to look at further parameters of your data, such as energy spectra, ARM distributions (for gamma-ray and electrons), interaction distances, scatter angle distributions, polarization, time distribution, and several more.

The main reference for Mimrec is: A. Zoglauer et al., "Design, Implementation, and Optimization of MEGAlib's image reconstrcution tool Mimrec", NIM A 652, 2011

Spectralyzer - new in 2.24

The latest addition to MEGAlib is its spectral analyzer, which starts with an input spectrum and tries to identify nuclear isotopes through classifying nuclear lines in the spectrum. Revan and Mimrec can access the spectralyzer. It is still in beta!

The main reference for Spectralyzer is: M. Galloway et al., "Spectral Analysis for the High-efficiency Multimode Imager", NSS Conference Record 2010

Realta - new in 2.24

Another new addition (or latest revival of a very old tool) is Realta, MEGAlib's real-time analyzer. It accepts data via a TCP/IP connection and then performs coincidence search, event reconstruction, image reconstruction, and spectral analysis all in real-time in several threads. Realta is also still in beta status.

The main reference for Realta is: A. Zoglauer et al., "Status of MEGAlib's Real-Time Analysis Tool Realta", NSS Conference Record 2011

Requirements

MEGAlib requires a few additional programs. In order to determine which version you need, first download MEGAlib and run the configure script. It will tell you which version of ROOT and GEANT4 it desires.

In general, you require the following software components:

1. A fully functional up-to-date Linux OS or Mac OS X (v10.5 or higher) - Windows is not wholeheartedly supported (although you will find a solution file for Visual Studio which will compile some of the MEGAlib programs, but not (yet) cosima). The status of the different UNIX systems is unknown (simply because it has not been tested). The reference systems (i.e. the system used to code MEGAlib) is Ubuntu Lucid Lynx (10.4). If you want to use anything else, especially newer, you might have to make things compatible by yourself!
2. In addition, make sure you have installed at least gcc 3.3 and all the usual development libraries (make, etc.).
3. Install ROOT.
4. It is highly recommended to also install Geant4.
5. If you want to do MGGPOD simulations: Install the latest version of Georg Weidenspointner's MGGPOD. In addition you need also the FTOOLS.

License

MEGAlib can be used freely for all non-commercial scientific, medical, and threat detection purposes on the condition that MEGAlib is correctly cited in all resulting publications. For more details see the license file.

The master reference is:

Download

MEGAlib should only be retrieved from the MEGAlib cvs directory. The current "stable" version is 2.24. However, I never check in anything which I expect not to work, thus even using the latest development version should be safe.

First you have to login (The password for the user anonymous is gamma-ray):

To checkout the latest development version use:

Alternatively, to checkout the latest non-development version do:

For the details see: MEGAlib/doc/Installation.pdf

While the latest version is only ailable via cvs, in case you have trouble accessing the repository, a tar ball can be found here: MEGAlib_2.24.00.tgz

Installation

You can find a detailed installation description in the file MEGAlib/doc/Installation.pdf

Please take also a look at the change log for the important changes between the versions: ChangeLog.txt

Documentation

The definitely not complete documentation can be found in these pdf-file: MEGAlib (general overview, old), Geomega (geometry, up-to-date), Cosima (Geant4 simulations, up-to-date).

Bug reports

Bug reports go to: Andreas Zoglauer, "zog (at) ssl (dot) berkeley (dot) edu" - please be specific, provide me with information about what version you are using, let me know how to reproduce the problem, and send me an example! Finally, attach the output of the bash script config/configure_checkenvironment to your email, because it reveals most misconfigurations.