SN@ilWare Analysis Modules

This repository holds several modules, one per directory, for SN@ilWare framework. It also contains the basic configuration to run the processing of SuperNEMO data through the concept of modules as described in these talks. Then, the content of this file is to provide a minimal working environment in order to run the bxdpp_processing binary1.

1

here, we assume that Cadfael, Bayeux & Falaise libraries have been successfully installed


Repository content

The following analysis modules are currently available :

snemo_control_plot
This module produce general plots of different physical information inside different data bank. For example, it plots the number of Geiger hits within the simulated data bank and within the calibrated data bank, the number of calorimeters…
snemo_bb0nu_studies
This module calculates 0ν sensitivity for SuperNEMO experiment. It succesively builds the energy distribution of signal & backgrounds, determines the efficiency and finally extracts the 0ν sensitivity given experimental conditions (namely exposure time, isotope mass…).
snemo_detector_efficiency
This module computes the efficiency of each sensitive detector volumes of SuperNEMO experiment i.e. main wall calorimeter, X-wall calorimeter, γ-vetos and Geiger cells.
snemo_vertex_resolution
This module shows the efficiency of vertex reconstruction by plotting the vertex position resolution on the source foil as well as on the calorimeter walls.
snemo_foil_vertex_distribution
This module produces a 2D distribution of the vertices on the source foil. It can be used either for simulated data to get the true vertices distribution or for reconstructed particle tracks to get vertices distribution from detector acceptance.
snemo_bremsstrahlung_studies
This module studies bremsstrahlung production within the source foil. It plots, for instance, the energy distributions of the primary electron and the emitted γ and the angular distribution of particles.
snemo_gamma_tracking_studies
This module studies the γ tracking efficiency by comparing the true simulated sequence of calorimeters associated to a gamma track to the one deduced from γ tracking algorithm.

The following package also provides :

README.org
The file you are currently holds the pipeline configuration + the documentation on how to use the SuperNEMO modules.
Makefile
The Makefile allows to generate the pipeline configuration by parsing and tangling this file i.e. README.org (see below).

The README.org file is organised using org-babel and its ability to execute source code. It requires then a recent installation of emacs2 which bundles org. Without entering into too much details regarding org-babel abilities, the basic idea is to give a "literate" way to navigate through the different sections, each of them representing a part of the pipeline configuration. Moreover, using org folding/unfolding capability, item can be hide and the user can focus on relevant parts.

2

At the time of writing this document, emacs version is 24.3.1


To export the different configuration files, you can run org-babel-tangle within emacs instance3 which will tangle each code block into the given file or use the associated Makefile. The author recommends to use the Makefile since the tangling process is asynchronous and thus, does not freeze your emacs (org-babel-tangle "occupies" emacs during its execution).

3

Emacs lisp function can be run using ALT-x command and typing the function name.


Pipeline general configuration

SN@ilWare implements the concept of data processing pipeline. An event record object is passed through a chain of data processing modules, each of them being responsible for a given task.

Modules are declared in each subdirectory, each one reponsible of a dedicated task. There is no need to include them by hand since org-mode will automatically build the list of module files. Services are declared in section Services configuration. For more details on running SuperNEMO simulations and the concept behind modules/services see these mandatory presentations given by F. Mauger.

The @SNEMO_SIMULATION_MODULES_DIR@ corresponds to the directory where configuration files are going to be stored. This variable which varies from one installation to the other, is automatically change when the tangle process occurs. This is done via the Makefile which parse and replace this variable.

Module manager

This file is the main and central piece of code for loading all modules/services needed by dpp_processing binary. It provides links to module files and service files.

Logging priority

#@description Module manager logging priority
logging.priority : string = "warning"

#@description Embedded module factory debug flag
factory.debug : boolean = 0

#@description Embedded module factory 'no preload' flag
factory.no_preload : boolean = 0

Service manager configuration

#@description The configuration file of the embedded service manager
service_manager.configuration : string[1] as path = \
    "@SNEMO_SIMULATION_MODULES_DIR@/service_manager.conf"

Configuration files for modules

#@description The configuration files for modules
modules.configuration_files : string[7] as path = \
    "@SNEMO_SIMULATION_MODULES_DIR@/snemo_foil_vertex_distribution_module.conf" \
    "@SNEMO_SIMULATION_MODULES_DIR@/snemo_vertex_resolution_module.conf" \
    "@SNEMO_SIMULATION_MODULES_DIR@/snemo_detector_efficiency_module.conf" \
    "@SNEMO_SIMULATION_MODULES_DIR@/snemo_bb0nu_studies_module.conf" \
    "@SNEMO_SIMULATION_MODULES_DIR@/snemo_bremsstrahlung_studies_module.conf" \
    "@SNEMO_SIMULATION_MODULES_DIR@/snemo_control_plot_module.conf" \
    "@SNEMO_SIMULATION_MODULES_DIR@/snemo_gt_studies_module.conf"

Service manager

Logging priority

#@description Service manager logging priority
logging.priority : string = "warning"

Name & description

#@description The name of the service manager
name : string = "sn_service_manager"

#@description The description of the service manager
description : string = "A SuperNEMO service manager"

List of service files

#@description The list of files that describe services
services.configuration_files : string[1] as path = \
    "@SNEMO_SIMULATION_MODULES_DIR@/services.conf"

DLL loader

Libraries

This part set the different libraries to be loaded at runtime. The following table sets the libraries:

Table 1: Libraries to be used by snemo_simulation_modules.
Falaise $SNAILWARE_PRO_DIR/falaise/install/lib64/libFalaise.so 
#@description A sample list of setups
#@key_label   "name"
#@meta_label  "filename"
[name="libsnemo_gamma_tracking_studies" filename="/home/garrido/Workdir/NEMO/supernemo/simulations/snemo_analysis_modules/./snemo_gamma_tracking_studies/install/lib/libsnemo_gamma_tracking_studies.so"]
#config The libsnemo_gamma_tracking_studies library
autoload : boolean = 1
[name="libsnemo_detector_efficiency" filename="/home/garrido/Workdir/NEMO/supernemo/simulations/snemo_analysis_modules/./snemo_detector_efficiency/install/lib/libsnemo_detector_efficiency.so"]
#config The libsnemo_detector_efficiency library
autoload : boolean = 1
[name="libsnemo_vertex_resolution" filename="/home/garrido/Workdir/NEMO/supernemo/simulations/snemo_analysis_modules/./snemo_vertex_resolution/install/lib/libsnemo_vertex_resolution.so"]
#config The libsnemo_vertex_resolution library
autoload : boolean = 1
[name="libsnemo_bb0nu_studies" filename="/home/garrido/Workdir/NEMO/supernemo/simulations/snemo_analysis_modules/./snemo_bb0nu_studies/install/lib/libsnemo_bb0nu_studies.so"]
#config The libsnemo_bb0nu_studies library
autoload : boolean = 1
[name="libsnemo_control_plot" filename="/home/garrido/Workdir/NEMO/supernemo/simulations/snemo_analysis_modules/./snemo_control_plot/install/lib/libsnemo_control_plot.so"]
#config The libsnemo_control_plot library
autoload : boolean = 1
[name="libsnemo_bremsstrahlung_studies" filename="/home/garrido/Workdir/NEMO/supernemo/simulations/snemo_analysis_modules/./snemo_bremsstrahlung_studies/install/lib/libsnemo_bremsstrahlung_studies.so"]
#config The libsnemo_bremsstrahlung_studies library
autoload : boolean = 1
[name="libsnemo_foil_vertex_distribution" filename="/home/garrido/Workdir/NEMO/supernemo/simulations/snemo_analysis_modules/./snemo_foil_vertex_distribution/install/lib/libsnemo_foil_vertex_distribution.so"]
#config The libsnemo_foil_vertex_distribution library
autoload : boolean = 1
[name="Falaise" filename="$SNAILWARE_PRO_DIR/falaise/install/lib64/libFalaise.so"]
#config The Falaise library
autoload : boolean = 1

Services configuration

A service generally hosts a specific resource that can be shared by many other software components, including other services or data processing modules (see SN@ilWare FAQ).

Preamble

#@description A sample list of setups
#@key_label   "name"
#@meta_label  "type"

Context service

[name="Ctx" type="dpp::context_service"]

#@description Logging priority
logging.priority : string = "warning"

#@description File from which the context is to be loaded at program start
load.file : string as path  = "/tmp/${USER}/snemo.d/snemo_context.conf"

#@description File to store the context at program termination
store.file : string as path = "/tmp/${USER}/snemo.d/snemo_context_end.conf"

#@description Flag to backup the former context load file
backup.file : string as path = "/tmp/${USER}/snemo.d/snemo_context_bak.conf"

Geometry service

The following code block declares the geometry service to properly load all the geometry and material construction of the detector. This service, only declared here, can be used by several operations like calibration, particle track reconstruction … but all of them will use the same geometry. 

[name="Geo" type="geomtools::geometry_service"]

#@description Logging priority
logging.priority : string = "warning"

#@description Embedded SuperNEMO geometry manager main configuration file
manager.configuration_file : string as path = \
    "@falaise:config/snemo/demonstrator/geometry/3.0/manager.conf"

#@description Embedded SuperNEMO geometry manager must build its mapping lookup table
manager.build_mapping : boolean = 1

#@description Embedded geometry manager's mapping lookup table does not exclude any geometry category
manager.no_excluded_categories : boolean = 1

Histogram service

The histogram service provides an esay way to handle histogram plot from different modules (mainly plot modules). It provides a service where 1D or 2D histograms can be added to a histogram dictionnary.

Declaration

[name="Histo" type="dpp::histogram_service"]

Description & priority

#@description Logging priority
logging.priority : string = "warning"

#@description The description string of the embedded pool of histograms
pool.description : string = "SuperNEMO histograms"

Running SN@ilWare processing chain

Source code compilation

First, you need to compile the module files within its directory. The build system used is cmake and a CMakeLists.txt file is provided to correctly setup the dependencies. Nevertheless, this implies that you have already and correctly installed Cadfael, Bayeux and Falaise. Then, you can configure, build and install a module by doing 

cd <path to your module>
mkdir build && cd build
cmake                                               \
    -DCMAKE_PREFIX_PATH="<path to Falaise install>" \
    -DCMAKE_INSTALL_PREFIX=../install               \
    ../source
make install

After a successful build, you will get an install directory holding a shared library file. The library is automatically added to the list of libraries to be loaded at running time by the tangling process (see below).

Tangling configuration

Second, you have to tangle this file. As explained in the Content section, you may use the dedicated Makefile to generate the pipeline configuration. Just run make within this working directory4.

4

on multicore machine you can also try to do make -jX where X is the number of processors.


Use and execute a module

Running processing pipeline is done by the bxdpp_processing program provided by dpp library. Its call is pretty simple and only implies to have a module manager file and the name of the module to be run for instance, bb0nu_halflife_limit_module. Nevertheless, you need to dynamically load the library(ies) which holds the needed modules. Then, you can use the dlls.conf file built in section DLL loader by writing 

bxdpp_processing                                            \
    --module-manager-config $PWD/config/module_manager.conf \
    --module bb0nu_halflife_limit_module                    \
    --dll-config $PWD/config/dlls.conf                      \
    --input-file <path to a data record>

It will run the bb0nu_halflife_limit_module over the input file5 and it will generate a ROOT file containing several histograms. This file is located by default, in /tmp/${USER}/snemo.d directory under the snemo_bb0nu_halflife_limit_histos.root name. You can change the output directory and output file name in this section.

5

here, we assume that you already have generated a data record.


File under version control - commit e6cbf11 - 2015-02-28