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 binary[fn:1].

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 emacs[fn:2] 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.

To export the different configuration files, you can run org-babel-tangle within emacs instance[fn:3] 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).

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_ANALYSIS_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.

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.

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

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

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

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

#@description The configuration files for modules
<<file_listing(prefix="modules.configuration_files", pattern="_module")>>

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

#@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"

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

echo '#@description A sample list of setups'
echo '#@key_label   "name"'
echo '#@meta_label  "filename"'

# Local dll from snemo_simulation_modules
local_dlls=($(find . -name "*.so"))
for dll in ${local_dlls[@]}
do
    if [[ $dll == *"install"* ]]; then
        dllname=$(basename ${dll/.so/})
        echo '[name="'${dllname}'" filename="'$(pwd)/${dll}'"]'
        echo '#config The '${dllname}' library'
        echo 'autoload : boolean = true'
    fi
done

# Build global dll
arr_name=(${name})
arr_filename=($filename)
for ((i=0; i < ${#arr_name[@]}; i++))
do
    dll=${arr_name[$i]}
    dllpath=${arr_filename[$i]}
    if [ "$dllpath" != "none" ]; then
        echo '[name="'$dll'" filename="'$dllpath'"]'
    else
        echo '[name="'$dll'" filename=""]'
    fi
    echo '#config The '$dll' library'
    echo 'autoload : boolean = true'
    echo
done

<<dll_loader(dll_libraries[*,0],dll_libraries[*,1])>>

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).

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

[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"

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 = true

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

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.

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

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

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

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).

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 directory[fn:4].

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 file[fn:5] 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.

[fn:1] here, we assume that Cadfael, Bayeux & Falaise libraries have been successfully installed

[fn:2] At the time of writing this document, emacs version is 24.3.1

[fn:3] Emacs lisp function can be run using ALT-x command and typing the function name.

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

[fn:5] here, we assume that you already have generated a data record.