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.

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

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

#@description The configuration file of the embedded service manager
service_manager.configuration : string[1] as path = \
    "@SNEMO_SIMULATION_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_SIMULATION_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 = 1'
    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 = 1'
    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 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"

Templates for histogram may be provided to reduce the amount of configuration of individual histogram. For instance, plotting the energy distributions of several channels may only need one general histogram definition which gives the x-axis boundaries and x-binning.

#@description The configuration files for modules
<<file_listing(prefix="pool.histo.setups", pattern="_template")>>

First, you need 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].

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

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

After a successful build, you will get an install directory holding the libsnemo_bb0nu_studies.so file. Assuming you are under bash shell, you will need to add it to your LD_LIBRARY_PATH by doing

export LD_LIBRARY_PATH=${PWD}/install/lib:${LD_LIBRARY_PATH}

Another approach, maybe less intrusive, will be to set the LD_LIBRARY_PATH when running the bxdpp_processing binary. You can for example write something like

LD_LIBRARY_PATH=${PWD}/install/lib:${LD_LIBRARY_PATH} bxdpp_processing ...

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 i.e. bb0nu_halflife_limit_module. Nevertheless, you need to dynamically load the library(ies) which holds the needed modules.

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

<library>_bio represents libraries which holds event data models such as mctools_bio and sncore_bio. Regarding the input data file and its content, you will need to load both to be able to retrieve simulated_data bank (mctools_bio) or specific SuperNEMO banks (sncore_bio and snanalysis_bio). Then, you can use the dlls.conf file built in section <a href=”DLL loader”>DLL loader by writing

dpp_processing                                                       \
    --module-manager-config $PWD/config/module_manager.conf \
    --module bb0nu_halflife_limit_module                             \
    --load-dll snemo_bb0nu_studies                                   \
    --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.