KaliVeda data analysis framework

KaliVeda
indra


About KaliVeda

KaliVeda is an object oriented data analysis framework based on ROOT. Its main purpose is to provide simulation and analysis tools for the INDRA charged particle multidetector used in the study of nuclear multifragmentation at GANIL.

However, it has been conceived in such a way as to permit the simulation of many other charged particle detectors, as well as being adapted to the analysis of general multiparticle events encountered in heavy ion collisions.

KaliVeda is developed and maintained for 32- and 64-bit Linux systems (tested on Ubuntu, Scientific Linux, Fedora).


Getting started


To download and install KaliVeda, see below.

The Data Analysis page is a hands-on quick-start guide to analysing INDRA data within the KaliVeda environment. You can also try the introductory courses on the Tutorials page.

Examples of classes for analysing data can be found here.

The Commands page documents various GUI and command-line tools provided by KaliVeda.

The Reference Guide page has links to the documentation of every class in the KaliVeda toolkit.

For information on configuring the KaliVeda environment to suit your needs, see the Configuration page.


Getting help


For help, support and discussion, you can ask a question here.

Click here to join the mailing list, KALIVEDA-L@IN2P3.FR, for important announcements.

If you find a bug, please report it to our Launchpad bug-tracking system.


Getting involved


KaliVeda is an open-source project which uses Launchpad as an integrated code-hosting platform, specification and bug tracker. We would love you to contribute, which we try to encourage through Launchpad's Mentoring system to help new collaborators implement bugs and blueprints that are an ideal introduction to the project.

For more details, see the KaliVeda project page on Launchpad, and click on "Mentoring available".


Download and install


Ubuntu packages are available for series 2.0! See the Users Guide for details on how to obtain the packages.

Source tarballs for official releases can be downloaded from Downloads
Source code is also freely available as bazaar branches hosted on Launchpad (see Code)
Installation instructions and details of the build system (Makefile targets & options) can be found here.


Overview

Here is a brief overview of the different tools provided by KaliVeda:

Particles & Nuclei
Nuclear Reactions
Multiparticle Events
Materials & Detectors
Interface to Data Acquisition System
Detector Calibration
Database of Detector Parameters
Multidetector Arrays
Multidetector Array Geometry
Charged Particle Identification
Particle and Event Reconstruction
Global Variables for Event Analysis

Particles & Nuclei

Relativistic kinematics of massive particles are the basis for the KVParticle base class, itself derived from TLorentzVector. This class gives all information on particle kinematics, in a variety of different user-defined Lorentz-boosted frames (see KVParticle::SetFrame).

In child class KVNucleus we add specific nuclear properties: atomic number, mass number, binding energy, mass excess, excitation energy. This class includes a mass table for nearly all known nuclides, and a few commonly used methods for estimating the nuclear mass when only the atomic number Z is known. In addition, nuclear arithmetic is possible using the usual '+', '-', '+=' and '-=' operators: this allows to calculate very simply the kinematics and excitation energy of the nucleus or nuclei resulting from capture or emission of nuclei by other nuclei.

Nuclear Reactions

The class KV2Body handles calculation of many useful quantities associated with nuclear reactions such as:

The laboratory and centre of mass scattering angle and energy of projectile or target can be calculated for any given outgoing projectile laboratory angle.

Multiparticle Events

KVEvent is a base class for the description of events resulting from nuclear reactions, composed of a number (multiplicity) of different nuclei. Looping over particles in the event is made simple using the GetNextParticle() iterator. The event kinematics can be "viewed" in different Lorentz frames defined by the user. The simulation of the detection of such an event by a multidetector array (filtering simulation) is achieved using KVMultiDetArray::DetectEvent.

Materials & Detectors

The main purpose of the KVMaterial class used to describe different materials in KaliVeda is to calculate the energy losses of heavy ions in targets and detectors, for use in detector simulation, event filtering, and also data calibration. Ideally this class should be replaced by an interface to e.g. GEANT4 and/or the ROOT geometry classes - this would also allow easy visualisation of detector structures and event geometries.

KVDetector is a base class for the description of (heavy ion) detectors, itself derived from KVMaterial. Whereas a KVMaterial object represents a piece of matter which can slow or stop heavy ions, a KVDetector associates one or more layers of materials with some kind of electronics so that the result of the passage of a charged particle in the "active" layer of the detector is some kind of signal(s); this signal is stored and later read back for analysis by some data acquisition system; the signal can be calibrated by various methods; after identification of a particle (see below) its energy loss in the detector corrected for dead zones, non-active layers, or particle-dependent (e.g. charge and/or mass-dependent) effects can be calculated.

Interface to Data Acquisition System

The KVACQParam class provides a rudimentary interface between detectors and the corresponding acquisition parameters, e.g. as in raw acquisition data for INDRA read from GANIL run files. It also gives access to coder pedestal values, as classes describing the electronics associated to detectors have not yet been fully implemented.

Detector Calibration

Base class KVCalibrator is provided for the implementation of detector calibration procedures. Each detector has a dedicated list of calibrator objects which associate a set of parameters to some method of calculating the calibrated energy loss from the detector's raw data. It is possible to visualise the transfer function (calibrated energy) vs. (raw data) by using the KVCalibrator::MakeGraph method.

Database of Detector Parameters

Parameters concerning detector status, physical characteristics, identification procedures, energy calibration, etc., for different runs of an experimental campaign are stored in a database implemented by classes derived from KVDataBase, KVDBTable, KVDBRecord. These include: KVDBRun for the description of a given experimental run; KVDBParameterSet which holds the identification or calibration parameters for a given detector; KVDBTape which describes a data acquisition tape (DLT); KVDBSystem which describes a given reaction studied over several runs.

Multidetector Arrays

The KVMultiDetArray base class for the description of multidetector arrays provides the following functionalities:

Obviously it also provides access to all its constituent detectors, identification telescopes, etc. The target for the current experimental run is also accessible via KVMultiDetArray::GetTarget.

Multidetector Array Geometry

The base class for detector positioning is KVPosition. It represents a solid angle element (theta_min, theta_max, phi_min, phi_max) at a given distance from the origin of the coordinate system (taken to be the target position by convention). This class provides methods for establishing the relative positioning of different elements of a multidetector array, deciding if two detectors are overlapping, in angular alignment, or if one has a smaller opening angle than the other, etc. Interfaces to the ROOT geometry classes exist to allow easy visualisation of detector structures and event geometries.

Detectors cannot be directly placed into a multidetector array geometry (KVDetector class has no notion of positioning), they first have to be incorporated into KVTelescope structures. A KVTelescope, as the name suggests, is a sandwich of detector layers with the same angular dimensions, typically used for charged particle identification, but can in fact consist of a single detector. This is an unsatisfactory and rather confusing state of affairs which ought to be resolved or at least improved, especially as the abstract notion of "identification telescope" is actually implemented in the class KVIDTelescope (see below).

There are two further levels in the geometrical hierarchy: KVRing and KVLayer.

A KVRing is a collection of telescopes occupying a certain solid angle, all at the same distance from the origin (target). The name 'ring' comes from the axially-symmetric substructures used in multidetectors such as INDRA, but a KVRing can in principle have any form; it may even be composed of a single KVTelescope/detector. In axially-symmetric multidetector geometries the KVRings are numbered according to their polar angle, and this numbering is used to give distinguishing names to the same types of detectors as a function of their position in the array.

A KVLayer is a collection of rings of telescopes (usually, though not necessarily, of the same type). As KVTelescopes can only associate detectors with the same angular dimensions, this class is necessary to describe structures in which detectors of different opening angles are aligned with the target.

Finally, the 'ancillary' class KVGroup is used to subdivide the array structure into groups of telescopes from different layers which share at least one common telescope (that with the largest opening angle). This is useful for simulating particle detection by the array (one first locates the group through which the particle will pass, and then the telescopes in the group, rather than testing all the telescopes of the array), and even essential when reconstructing particles from data (taking into account and eventually correcting the simultaneous passage of particles through the common telescope of the group). Once the structure of the multidetector array has been defined the corresponding groups are automatically determined.

Charged Particle Identification

Particle identification is based on the concept of identification telescopes - this is an abstract concept, a single detector can sometimes provide a full identification, and therefore be considered to be an identification 'telescope'. In the most general case, two detectors are associated in order to provide identification of charged particles (heavy ions) by the dE - E method. Each specific implementation defines its own Identify method in order to establish the identity of a reconstructed particle from the information stored in the telescope's detector(s), however a general algorithm for the calibration (i.e. determining the energy) of identified reconstructed particles is provided.

In the case where identification is based on the position of data points in the dE-E plane, it is common to use identification grids composed of lines/cuts corresponding to all possible identifiable nuclei. Base classes are provided for lines and grids used to identify only the atomic number Z of the detected particle (KVIDZLine, KVIDZGrid), or both Z and the mass number, A (KVIDZALine, KVIDZAGrid). Although the specific details of the identification are left to be determined by derived classes, it is most likely to use the general algorithm defined in KVIDGrid for finding the closest identification line to a (dE,E) point, as well as the WhereAmI method implemented in KVIDLine which allows e.g. to decide whether a data point is identifiable based on its position relative to some cut(s) in the (dE,E) plane.

Particle and Event Reconstruction

A 'raw' event as 'seen' by the multidetector array is described as a list of groups hit by particles, as deduced from the active acqusition data parameters. This is handled by class KVDetectorEvent, and is generated by KVMultiDetArray::GetDetectorEvent (only the multidetector array can link raw acquisition data to physical detectors with their geometrical location etc.).

The next step is to analyse the hit groups in order to reconstruct physical particles, which constitute a reconstructed event. The base class for particles reconstructed from energy losses in successive detectors is KVReconstructedNucleus, and the base class for reconstructed events is KVReconstructedEvent. KVReconstructedEvent::ReconstructEvent takes a KVDetectorEvent 'raw' event and turns it into a list of reconstructed particles. Particle identification and calibration then takes place using the identification telescopes hit by each particle.

Global Variables for Event Analysis

A set of classes to describe many common global variables used for the analysis of multibody heavy ion reactions is provided. These are based on class KVVarGlob. A common use of such variables is to permit event sorting, and classes dedicated to this task are derived from KVTrieur.