KaliVeda
Toolkit for HIC analysis
Data management

Table of Contents

The management of data for a given experiment or experimental campaign is handled by a KVDataSet object, which brings together:

  • the description of the experimental setup with a KVMultiDetArray or KVExpSetUp object;
  • a database containing a description of each studied reaction (projectile, energy, target characteristics, DAQ trigger, etc.), detector/array settings, calibration parameters, etc. (KVExpDB, KVExpSetUpDB)

Many different experiments or experimental campaigns can be grouped together and handled by a KVDataSetManager instance: such an object can be used to consult which datasets are available and change from one to another.

Accessing the data files for different experiments is handled by an object of KVDataRepository type: data may be accessed either locally on the host PC or remotely using e.g. IRODS or xrootd backends. Each KVDataRepository has an associated KVDataSetManager, which describes the list of experiments (KVDataSet objects) whose data is available from that source.

Several different KVDataRepository data sources may be handled by an instance of the KVDataRepositoryManager class.

In this chapter we will see how to use these objects to access the relevant information.

Consulting the catalogue - Dataset Manager

The list of datasets (experiments) known to a given installation of KaliVeda depends on which - if any - datasets were configured to be downloaded and used at build time (see the WITH_*_DATASETS CMake options in Appendix: KaliVeda build system). In order to consult the list of known datasets requires simply to initialise a KVDataSetManager object:

KVDataSetManager dsm
dsm.Init()
dsm.Print()
Dataset name=INDRA_camp1 (1st INDRA campaign (1993)) [ AVAILABLE: raw dst recon root]
Dataset name=INDRA_camp2 (2nd INDRA campaign (1994)) [ AVAILABLE: raw dst recon root]
...
name
char name[80]
KVDataSetManager
Manage all datasets contained in a given data repository.
Definition: KVDataSetManager.h:39
KVDataSetManager::Init
virtual Bool_t Init(KVDataRepository *=0)
Definition: KVDataSetManager.cpp:65

What you see in this list (if anything) will therefore depend on your specific installation, but in general for each dataset there is a line with its name, title, and a list of available data types (see below).

Note that the call to KVDataSetManager::Init() initialises a global pointer, gDataSetManager, with the address of the dataset manager object.

Consulting a specific dataset

Each dataset can be accessed from the manager using its name,

auto indra_camp1 = gDataSetManager->GetDataSet("INDRA_camp1")
KVDataSetManager::GetDataSet
KVDataSet * GetDataSet(Int_t) const
Return pointer to DataSet using index in list of all datasets, index>=0.
Definition: KVDataSetManager.cpp:378

but usually, in order to obtain useful information on a given dataset, it is necessary to make it the 'currently active dataset' by calling the method KVDataSet::cd() for the dataset in question, which can be done directly like so:

gDataSetManager->GetDataSet("INDRA_camp1")->cd()
KVDataSet::cd
void cd() const
Definition: KVDataSet.cpp:745

If the database of systems, runs, calibration parameters, etc. for the chosen dataset is out of date, this will automatically trigger an update of the database using the installed versions of the dataset files:

Info in <KVDataSet::OpenDataBase>: Updating database file
Info in <KVINDRADB1::OpenRLFile>: Opened file .../share/kaliveda/INDRA_camp1/Runlist.csv for reading
Info in <KVINDRADB1::ReadSystemList()>: Reading Systems parameters ...
New System : 129Xe + natSn 25 MeV/A
Zproj = 54 Ztarg = 50 targ_thick = 0.35 Ebeam = 24.981
Target natSn, Target for experiment
Collection name='KVSeqCollection_720', embedded list class='TList', size=1
KVMaterial: Sn (Tin)
Thickness 6.08696e-05 cm
Area density 0.00035 g/cm**2
-----------------------------------------------
Z = 50 atomic mass = 118.71
Density = 5.75 g/cm**3
[...]
size
size_t size(const MatrixT &matrix)
g
Option_t Option_t TPoint TPoint const char GetTextMagnitude GetFillStyle GetLineColor GetLineWidth GetMarkerStyle GetTextAlign GetTextColor GetTextSize void char Point_t Rectangle_t WindowAttributes_t Float_t Float_t g
KVExpDB::ReadSystemList
virtual void ReadSystemList()
Definition: KVExpDB.cpp:249
KVMaterial
Description of physical materials used to construct detectors & targets; interface to range tables.
Definition: KVMaterial.h:94
KVUnits::MeV
const long double MeV
energies
Definition: KVUnits.h:88
KVUnits::cm
const long double cm
Definition: KVUnits.h:66
Info
void Info(const char *location, const char *fmt,...)

etc. etc.

Note that the call to KVDataSet::cd() initialises 2 global pointers:

  • gDataSet, with the address of the 'currently active dataset';
  • gExpDB, with the address of the database for the dataset

Systems, runs, calibrations - consulting the database

The experimental database (object of a class derived from KVExpDB) associated with the any dataset can be accessed in 3 ways:

// for any dataset known to the dataset manager
gDataSetManager->GetDataSet("...")->GetDataBase()->Print()
// for the currently active dataset
gDataSet->GetDataBase()->Print()
gExpDB->Print()
KVDataBase::Print
virtual void Print(Option_t *option="") const
Definition: KVDataBase.cpp:152
KVDataSet::GetDataBase
KVExpDB * GetDataBase(Option_t *opt="") const
Definition: KVDataSet.cpp:289

KVExpDB::Print() will show the structure of the database, in terms of 'tables':

gDataSetManager->GetDataSet("INDRAFAZIA.E818")->GetDataBase()->Print()
_______________________________________________________
KVExpSetUpDB : INDRAFAZIA.E818 <---> database
Available Tables :
Runs
Systems
INDRA.OoO Detectors
INDRA.Calibrations
FAZIA.OoO Detectors
FAZIA.Absent Detectors
FAZIA.Calibrations
_______________________________________________________
KVExpSetUpDB
Calibration database for experiments using coupled detector arrays.
Definition: KVExpSetUpDB.h:17

Each table can be accessed using the given name, and its contents reviewed:

// [assuming INDRAFAZIA.E818 is now the active dataset]
gExpDB->GetTable("Runs")->ls()
KVDBTable : Runs <---> List of available runs [3632 records]
gExpDB->GetTable("Runs")->GetRecords()->ls()
OBJ: KVHashList KVSeqCollection_782 Extended version of ROOT THashList : 0
OBJ: KVDBRun Run 1000 12C + 197Au[660] 13.75 MeV/A (q=4+ f=13.45MHz CSS1) : 0 at: 0x5af6847d6cd0
OBJ: KVDBRun Run 1001 12C + 197Au[660] 13.75 MeV/A (q=4+ f=13.45MHz CSS1) : 0 at: 0x5af684dccfa0
OBJ: KVDBRun Run 1002 12C + 197Au[660] 13.75 MeV/A (q=4+ f=13.45MHz CSS1) : 0 at: 0x5af6844b5630
OBJ: KVDBRun Run 1003 12C + 197Au[660] 13.75 MeV/A (q=4+ f=13.45MHz CSS1) : 0 at: 0x5af684cc1870
[...]
gExpDB->GetTable("Systems")->GetRecords()->ls()
OBJ: KVHashList KVSeqCollection_783 Extended version of ROOT THashList : 0
KVDBSystem : Poubelle Runs : 5002 10000 19000-19002 20000 21000-21005 22000-22003 23000-23006 39000 40000 41000 43006-43015 81000 82000 85000 86000 94000 121000-121009
KVDBSystem : 12C + 197Au[660] 13.75 MeV/A (q=4+ f=13.45MHz CSS1) Runs : 1000-1013
KVDBSystem : 12C + 197Au[980] 13.75 MeV/A (q=4+ f=13.45MHz CSS1) Runs : 2000-2017 3000-3019 4000-4029 5000-5001 6000
[...]
f
#define f(i)
q
float * q
KVDBRun
Description of an experimental run in database ,,.
Definition: KVDBRun.h:36
KVDBSystem
Database class used to store information on different colliding systems studied during an experiment....
Definition: KVDBSystem.h:52
KVDBTable
Table in a database.
Definition: KVDBTable.h:34
KVDBTable::GetRecords
virtual KVSeqCollection * GetRecords() const
Definition: KVDBTable.h:63
KVDBTable::ls
virtual void ls(Option_t *option="*") const
Definition: KVDBTable.cpp:106
KVDataBase::GetTable
virtual KVDBTable * GetTable(const Char_t *table) const
Definition: KVDataBase.h:159
KVHashList
Extended version of ROOT THashList.
Definition: KVHashList.h:29
TCollection::ls
void ls(Option_t *option="") const override
RooFit::Extended
RooCmdArg Extended(bool flag=true)
C
constexpr Double_t C()

Note that each run is described by a KVDBRun object, each system by a KVDBSystem object. For these two cases, more direct access is provided by other methods of KVExpDB:

gExpDB->GetRuns()->ls()
OBJ: KVHashList KVSeqCollection_782 Extended version of ROOT THashList : 0
OBJ: KVDBRun Run 1000 12C + 197Au[660] 13.75 MeV/A (q=4+ f=13.45MHz CSS1) : 0 at: 0x5af6847d6cd0
OBJ: KVDBRun Run 1001 12C + 197Au[660] 13.75 MeV/A (q=4+ f=13.45MHz CSS1) : 0 at: 0x5af684dccfa0
OBJ: KVDBRun Run 1002 12C + 197Au[660] 13.75 MeV/A (q=4+ f=13.45MHz CSS1) : 0 at: 0x5af6844b5630
OBJ: KVDBRun Run 1003 12C + 197Au[660] 13.75 MeV/A (q=4+ f=13.45MHz CSS1) : 0 at: 0x5af684cc1870
[...]
gExpDB->GetRunList() // returns entire list of runs in a KVNumberList!
gExpDB->GetDBRun(1001)->Print()
___________________________________________________
Run 1001 (12C + 197Au[660] 13.75 MeV/A (q=4+ f=13.45MHz CSS1))
System : 12C + 197Au[660] 13.75 MeV/A (q=4+ f=13.45MHz CSS1)
Target : 197Au
___________________________________________________
KVNameValueList:: : (0x5af684dcd058)
<Start Date=2022-04-02 14:42:26>
<End Date=2022-04-02 14:46:13>
___________________________________________________
KVNameValueList:: : (0x5af684dcd058)
<Size (MB)=999.153>
___________________________________________________
KVNameValueList:: : (0x5af684dcd058)
<Events_hi=0>
<Events_lo=218014>
___________________________________________________
gExpDB->GetSystems()->ls()
OBJ: KVHashList KVSeqCollection_783 Extended version of ROOT THashList : 0
KVDBSystem : Poubelle Runs : 5002 10000 19000-19002 20000 21000-21005 22000-22003 23000-23006 39000 40000 41000 43006-43015 81000 82000 85000 86000 94000 121000-121009
KVDBSystem : 12C + 197Au[660] 13.75 MeV/A (q=4+ f=13.45MHz CSS1) Runs : 1000-1013
KVDBSystem : 12C + 197Au[980] 13.75 MeV/A (q=4+ f=13.45MHz CSS1) Runs : 2000-2017 3000-3019 4000-4029 5000-5001 6000
[...]
gExpDB->GetSystem("12C + 197Au[660] 13.75 MeV/A (q=4+ f=13.45MHz CSS1)")->Print()
________________________________________________________
System : 12C + 197Au[660] 13.75 MeV/A (q=4+ f=13.45MHz CSS1)
Runs : 1000-1013
Zbeam : 6
Abeam : 12
Ebeam : 13.75 A.MeV
Ztarget : 79
Atarget : 197
Target Thickness : 0.66 mg/cm2
________________________________________________________
KVExpDB::GetRuns
virtual KVSeqCollection * GetRuns() const
Definition: KVExpDB.h:72
KVNameValueList
Handles lists of named parameters with different types, a list of KVNamedParameter objects.
Definition: KVNameValueList.h:116
KVUnits::mg
const long double mg
Definition: KVUnits.h:74
Print
void Print(std::ostream &os, const OptionType &opt)
End
void End()
Size
const char * Size

Note that for each database system corresponding to a reaction between a projectile and a target the corresponding kinematics object KV2Body can be retrieved simply with the method KVDBSystem::GetKinematics(), e.g.

gDataSetManager->GetDataSet("INDRA_camp2")->GetDataBase()->GetSystem("58Ni + 58Ni 32 MeV/A")->GetKinematics()->Print()
***** REACTION 58Ni + 58Ni ---> 58Ni + 58Ni ******
E.LAB = 1854.65 MEV QGG = 0 MEV
E.EXC = 0 MEV ==> Q-REACTION = 0 MEV
AVAILABLE ENERGY IN C.M. : ECM = 923.373 MEV (7.96012 MEV/A)
PROJECTILE VELOCITY IN LAB 7.66451 CM/NS ( 0.255661 * C )
VELOCITY OF C.M. 3.89701 CM/NS
ENERGY - VELOCITY OF NUCLEUS 1 IN CM : 461.687 MEV 3.89701 CM/NS (K=1)
ENERGY - VELOCITY OF NUCLEUS 2 IN CM : 461.687 MEV 3.89701 CM/NS (K=1)
ENERGY - VELOCITY OF NUCLEUS 3 IN CM : 461.687 MEV 3.89701 CM/NS (K=1)
ENERGY - VELOCITY OF NUCLEUS 4 IN CM : 461.687 MEV 3.89701 CM/NS (K=1)
MAXIMUM SCATTERING ANGLE IN LABORATORY
THETA #3# 90 DEG.
THETA #4# 90 DEG.
GRAZING ANGLE IN LABORATORY : PROJECTILE 3.21146 DEG.
GRAZING ANGLE IN LABORATORY : TARGET 86.7885 DEG.
KV2Body::Print
void Print(Option_t *opt="") const
Definition: KV2Body.cpp:813
KVDBSystem::GetKinematics
KV2Body * GetKinematics()
Definition: KVDBSystem.cpp:80
KVExpDB::GetSystem
virtual KVDBSystem * GetSystem(const Char_t *system) const
Definition: KVExpDB.h:85
E
constexpr Double_t E()

Experimental setup/detector geometry for dataset - the KVMultiDetArray

The experimental setup used during a particular experiment is described by a dedicated object derived from the KVMultiDetArray class (see Detector Array Geometries). This object can be built for a particular dataset using

KVMultiDetArray::MakeMultiDetector("[dataset name]" [, run_number])
// example: build INDRA 1st campaign array geometry
KVMultiDetArray::MakeMultiDetector("INDRA_camp1")
KVMultiDetArray::MakeMultiDetector
static KVMultiDetArray * MakeMultiDetector(const Char_t *dataset_name, Int_t run=-1, TString classname="KVMultiDetArray")
Definition: KVMultiDetArray.cpp:2033

Note that this method initialises a global pointer, gMultiDetArray, with the address of the detector geometry object.

Note that this method can be called straight after initialising a dataset manager - the associated dataset will be automatically made the 'current active dataset'.

The second, optional, argument is the number of a run from the dataset: if given, it will set any parameters of the array defined in the database to their values for that run (ionization chamber gas pressures, calibration parameters, identification grids, etc. etc.). It is equivalent to doing:

gMultiDetArray->SetParameters([run number])
KVMultiDetArray::SetParameters
virtual void SetParameters(UInt_t n, Bool_t physics_parameters_only=kFALSE)
Definition: KVMultiDetArray.cpp:2192