Falaise  3.3.0
SuperNEMO Software Toolkit
Using The FLReconstruct Application

Table of Contents

Introduction to FLReconstruct

FLReconstruct's task is to read data from an output file generated by the SuperNEMO simulation or detector, perform reconstruction on each event in the data, and write the reconstructed data to an output file. It uses a pipeline architecture for event processing, the pipeline is constructed as a sequence of "modules", the sequence of modules being selected by the user (i.e. you) at runtime. Falaise provides a standard set of pipelines and modules, and you can write your own custom pipeline scripts and modules which FLReconstruct can load at runtime via a plugin mechanism.

Here we present a brief overview of running FLReconstruct from the command line using the standard pipeline scripts. The more advanced topics of scripting the pipeline and writing custom modules are covered in the Writing FLReconstruct Pipeline Scripts and Writing FLReconstruct Modules tutorials.

Using FLReconstruct on the Command Line

The flreconstruct program is a command line application just like any other Unix style program (e.g. ls). In the following, we will write commands assuming that flreconstruct is in your path. If it is not, simply use the relative or absolute path to flreconstruct.

You can get help on the options that can be passed to flreconstruct by running it with the -h or --help options, e.g.

$ flreconstruct --help
flreconstruct (3.0.0) : SuperNEMO reconstruction program
Usage:
flreconstruct [options]
Options:
-h [ --help ] print this help message
--help-module-list list available modules and exit
--help-module name print help for a single module and exit
--help-pipeline-list list available pipeline configurations
and exit
--version print version number
-V [ --verbosity ] level set the verbosity level
-P [ --modulo ] period (=0) progress modulo on number of events
-u [ --user-profile ] name (=normal) set the user profile ("expert",
"normal", "production")
-M [ --input-metadata-file ] file file from which to load metadata
-m [ --output-metadata-file ] file file in which to store metadata
-E [ --embedded-metadata ] flag (=0) flag to (de)activate recording of
metadata in the reconstruction results
output file
-p [ --pipeline ] file pipeline script
-i [ --input-file ] file file from which to read input data
(simulation, real)
-o [ --output-file ] file file in which to store reconstruction
results

The --version option provides detailed information of the current status of the application, including which libraries it uses:

$ flreconstruct --version
flreconstruct 3.0.0
Copyright (C) 2013-2017 SuperNEMO Collaboration
flreconstruct uses the following external libraries:
* Falaise : 3.0.0
* Bayeux : 3.0.0
* Boost : 106000

The exact versions you see will depend on the version you are using and the versions of external packages linked.

To examine a data file output by the flsimulate application, you need to supply, at minimum, an input file. By default, this will simply dump information on each event held in the file to standard output (i.e. the current terminal). For example, say we have a file example.brio, then we can dump events in that file by doing:

$ flreconstruct -i example.brio
flreconstruct::default:
`-- Bank 'SD' : "mctools::simulated_data"
|-- Properties : <empty>
| `-- <no property>
|-- Collection type : 1
|-- Collections of step hit handles :
| |-- Category 'calo' has 2 hit(s) [capacity=2]
| `-- Category 'gg' has 31 hit(s) [capacity=31]
|-- Primary event :
| |-- Auxiliary properties: <none>
| |-- Label : 'Se82.0nubb'
| |-- Time : 0 s
| |-- Particles: [2]
| | |-- Particle #0 :
| | | |-- Generation Id : <none>
| | | |-- Type : 3 (label='e-')
| | | |-- PDG code : <none>
| | | |-- Mass : 0.510999 MeV
| | | |-- Charge : -1 e
| | | |-- Time : 0 ns
| | | |-- Kinetic energy : 2.4231 MeV
| | | |-- Momentum : (-0.903124,0.824222,2.6178) MeV
| | | |-- Vertex : <no vertex>
| | | |-- Auxiliary properties: <none>
| | | `-- Valid : 1
| | `-- Particle #1 :
| | |-- Generation Id : <none>
| | |-- Type : 3 (label='e-')
| | |-- PDG code : <none>
| | |-- Mass : 0.510999 MeV
| | |-- Charge : -1 e
| | |-- Time : 0 ns
| | |-- Kinetic energy : 0.571898 MeV
| | |-- Momentum : (-0.700223,-0.622764,-0.182756) MeV
| | |-- Vertex : <no vertex>
| | |-- Auxiliary properties: <none>
| | `-- Valid : 1
| |-- GENBB weight : 1
| |-- Classification : '2e0p0g0a0X'
| `-- Valid: 1
`-- Vertex : (-0.0440134,1597.93,40.6704) mm
... further events ...
$

Quick start

Here we propose to run FLReconstruct with the default setup. Only an input simulation file is set from the command line.

We first generate a single simulated event, using the default simulation setup, and store it in an output file:

$ flsimulate -o example.brio
...

Then we process this file with a default pipeline:

$ flreconstruct -i example.brio

The output on the terminal is:

flreconstruct::default:
`-- Bank 'SD' : "mctools::simulated_data"
|-- Properties : <empty>
| `-- <no property>
|-- Collection type : 1
|-- Collections of step hit handles :
| |-- Category 'calo' has 2 hit(s) [capacity=2]
| `-- Category 'gg' has 27 hit(s) [capacity=27]
|-- Primary event :
| |-- Auxiliary properties: <none>
| |-- Label : 'Se82.0nubb'
| |-- Time : 0 ns
| |-- Vertex : <none>
| |-- Particles: [2]
| | |-- Particle #0 :
| | | |-- Generation Id : <none>
| | | |-- Type : 3 (label='e-')
| | | |-- PDG code : <none>
| | | |-- Mass : 0.510999 MeV
| | | |-- Charge : -1 e
| | | |-- Time : 0 ns
| | | |-- Kinetic energy : 2.03412 MeV
| | | |-- Momentum : (0.780969,2.36733,0.0484636) MeV
| | | |-- Vertex : <no vertex>
| | | |-- Auxiliary properties: <none>
| | | `-- Valid : 1
| | `-- Particle #1 :
| | |-- Generation Id : <none>
| | |-- Type : 3 (label='e-')
| | |-- PDG code : <none>
| | |-- Mass : 0.510999 MeV
| | |-- Charge : -1 e
| | |-- Time : 0 ns
| | |-- Kinetic energy : 0.960875 MeV
| | |-- Momentum : (1.3576,0.0410453,-0.246035) MeV
| | |-- Vertex : <no vertex>
| | |-- Auxiliary properties: <none>
| | `-- Valid : 1
| |-- GENBB weight : 1
| |-- Classification : '2e0p0g0a0X'
| `-- Valid: 1
|-- Time : <none>
`-- Vertex : (-0.0683336,-966.449,-773.204) mm

As we can see, the default behaviour of FLReconstruct is to print the contents of the event record(s) in the standard output. We can thus identify the simulated event record with its SD bank (simulated data) which contains the informations about the generated primary event, the original vertex and some collections of truth hits (here in the calo and gg hit categories).

Scripting FLReconstruct

As seen above, if supplied with no other information other than an input file, flreconstruct simply dumps data to standard output. To work with and process the data, a configuration script must be provided by the user.

Basic Script Syntax

FLreconstruct scripts use the datatools::multi_properties format from Bayeux. The script must begin with a mandatory header:

#@description a short description of the reconstruction run
#@key_label "name"
#@meta_label "type"

The '#@description' line is optional but highly recommended.

Comments can be placed at any point in the script. Just prepend a sharp ('#') symbol to any comment line. You may also prepend a comment at the end of a line:

# This is a single commented line
{...some script command...} # Comment starts at the end of the line
# This is
# a commented
# block

Note that lines starting with `'#@`' are generally special meta-comments with embedded commands. They should not be considered as comments. As a matter of rule, the use of lines starting with '#@' is reserved for system use.

After the header, the script contains sections. A section starts with a section definition line with two identifiers:

The syntax is:

[name="SectionName" type="flreconstruct::section"]
... section body ...

The section body uses the datatools::properties format from Bayeux. After the definition line, a short description may be optionally provided thanks to the '#@config' meta-comment:

#@config a short description of the purpose of the section

Then comes the section body which consists in a list of parameter setting directives. The format is:

#@description a short description of the parameter
NAME : TYPE [DECORATOR] = VALUE

where NAME is the identifier for the parameter, TYPE is its type and VALUE the selected value for this parameter. Some parameters may use an optional DECORATOR which gives additional information about the parameter's type or processing. Again, the #@description line is optional, but recommended. Example:

#@description The number of events to be processed
numberOfEvents : integer = 10000

How to run a mock calibration on simulated events

When we generate simulated events with FLSimulate, the so-called SD bank contains only raw information about truth calorimeter and tracker hits. In order to be able to reconstruct and analyze the events, we must apply a calibration procedure. This calibration procedure consists of determining physics/geometrical observables associated to hits : deposited energy, particle times of flight, hit positions in the geometry model and so on.

The so-called mock calibration computes the calibrated data associated to raw simulated data.

flr_mock_calib.png
Mock calibration algorithms applied to simulated events

The mock calibration consists of:

A new CD bank holding these data is added in the event record, alongside the raw SD bank.

To see this processing in action, we first prepare a set of 10 simulated events (using the default simulation setup), using the following simu.conf script for FLSimulate:

#@key_label "name"
#@meta_label "type"
[name="flsimulate" type="flsimulate::section"]
numberOfEvents : integer = 10

and run:

$ flsimulate -c simu.conf -o example.brio
...

The resulting example.brio file can be opened with the flvisualize application. We can visualize the first event where we will see any raw tracker/calorimeter hits, as well as the position of the decay vertex (cross on the source foil). An example event is shown below, and your view may differ as by default flsimulate will use different seeds on each run, and the styling/colours may also vary between machines:

flr_qs_sd_event.png
A simulated event

To process this data in flreconstruct and apply the mock calibration we create the rec.conf script with a custom pipeline inline module made of three consecutive modules. The first one is responsible of the calibration of the tracker hits. The second one is responsible of the calibration of the calorimeter hits. The last one simply prints the content of the events in the standard output:

#@key_label "name"
#@meta_label "type"
[name="pipeline" type="dpp::chain_module"]
modules : string[3] = "CalibrateTracker" "CalibrateCalorimeters" "Dump"
[name="CalibrateTracker" type="snemo::processing::mock_tracker_s2c_module"]
[name="CalibrateCalorimeters" type="snemo::processing::mock_calorimeter_s2c_module"]
[name="Dump" type="dpp::dump_module"]

We use default settings for each of the CalibrateTracker, CalibrateCalorimeters and Dump modules so the corresponding sections are empty.

We then run:

$ flreconstruct -i example.brio -p rec.conf -o example-cd.brio
...

The use of the Dump module prints the events in the terminal. Here is the first event:

|-- Bank 'CD' : "snemo::datamodel::calibrated_data"
| |-- Properties : <empty>
| | `-- <no property>
| |-- Calibrated calorimeter hits: 1
| | `-- Hit #0 : Id=0 GID=[1302:0.1.16.6.*] E=1027.5 keV t=2.10165 ns
| `-- Calibrated tracker hits: 23
| |-- Hit #0 : Id=0 GID=[1204:0.1.0.95] [prompt]
| |-- Hit #1 : Id=1 GID=[1204:0.1.1.96] [prompt]
| |-- Hit #2 : Id=2 GID=[1204:0.1.2.96] [prompt]
| |-- Hit #3 : Id=3 GID=[1204:0.1.2.97] [delayed]
| |-- Hit #4 : Id=4 GID=[1204:0.1.3.97] [prompt]
| |-- Hit #5 : Id=5 GID=[1204:0.1.4.98] [prompt]
| |-- Hit #6 : Id=6 GID=[1204:0.1.5.98] [prompt]
| |-- Hit #7 : Id=7 GID=[1204:0.1.5.99] [prompt]
| |-- Hit #8 : Id=8 GID=[1204:0.1.6.99] [prompt]
| |-- Hit #9 : Id=9 GID=[1204:0.1.6.100] [prompt]
| |-- Hit #10 : Id=10 GID=[1204:0.1.7.100] [prompt]
| |-- Hit #11 : Id=11 GID=[1204:0.1.7.101] [prompt]
| |-- Hit #12 : Id=12 GID=[1204:0.1.8.101] [prompt]
| |-- Hit #13 : Id=13 GID=[1204:0.1.8.102] [prompt]
| |-- Hit #14 : Id=14 GID=[1204:0.1.0.94] [prompt]
| |-- Hit #15 : Id=15 GID=[1204:0.1.1.94] [prompt]
| |-- Hit #16 : Id=16 GID=[1204:0.1.2.94] [prompt]
| |-- Hit #17 : Id=17 GID=[1204:0.1.3.94] [prompt]
| |-- Hit #18 : Id=18 GID=[1204:0.1.4.93] [prompt]
| |-- Hit #19 : Id=19 GID=[1204:0.1.5.93] [prompt]
| |-- Hit #20 : Id=20 GID=[1204:0.1.6.93] [prompt]
| |-- Hit #21 : Id=21 GID=[1204:0.1.7.93] [prompt]
| `-- Hit #22 : Id=22 GID=[1204:0.1.8.93] [prompt]
`-- Bank 'SD' : "mctools::simulated_data"
|-- Properties : <empty>
| `-- <no property>
|-- Collection type : 1
|-- Collections of step hit handles :
| |-- Category 'calo' has 1 hit(s) [capacity=1]
| `-- Category 'gg' has 25 hit(s) [capacity=25]
|-- Primary event :
| |-- Auxiliary properties: <none>
| |-- Label : 'Se82.0nubb'
| |-- Time : 0 ns
| |-- Vertex : <none>
| |-- Particles: [2]
| | |-- Particle #0 :
| | | |-- Generation Id : <none>
| | | |-- Type : 3 (label='e-')
| | | |-- PDG code : <none>
| | | |-- Mass : 0.510999 MeV
| | | |-- Charge : -1 e
| | | |-- Time : 0 ns
| | | |-- Kinetic energy : 1.1133 MeV
| | | |-- Momentum : (0.706726,-0.130119,-1.36412) MeV
| | | |-- Vertex : <no vertex>
| | | |-- Auxiliary properties: <none>
| | | `-- Valid : 1
| | `-- Particle #1 :
| | |-- Generation Id : <none>
| | |-- Type : 3 (label='e-')
| | |-- PDG code : <none>
| | |-- Mass : 0.510999 MeV
| | |-- Charge : -1 e
| | |-- Time : 0 ns
| | |-- Kinetic energy : 1.8817 MeV
| | |-- Momentum : (0.0921589,0.473499,2.28718) MeV
| | |-- Vertex : <no vertex>
| | |-- Auxiliary properties: <none>
| | `-- Valid : 1
| |-- GENBB weight : 1
| |-- Classification : '2e0p0g0a0X'
| `-- Valid: 1
|-- Time : <none>
`-- Vertex : (-0.0225505,1697.97,182.097) mm
...

We clearly see that a new CD bank (calibrated data) has been added to the event record. It contains two collections of hits, respectively calorimeter and tracker hits.

The example-cd.brio file output by flreconstruct and the pipeline script may be opened in flvisualize as before. Looking at the first event again, we can see additional rendering and information associated to the CD hits (as before, your output will differ due to different random number seeds used in flsimulate):

flr_qs_cd_event.png
A calibrated simulated event

The superimposed white circles on top of the colored ones represent the calibrated tracker hits for which the drift radius and longitudinal position along the anode wire have been computed from the truth hits' timestamps. Here, there is only one calorimeter hit, the total deposited energy in the block and time of entering the scintillator block are also computed (with respect to the arbitrary decay time set by the simulation engine).

How to run a tracking algorithm on simulated events

Now we know how to perform the calibration step, we are interested in the reconstruction of electron tracks in the tracking chamber. For that we need additional processing on top of the CD bank which is now available in the event record.

The reconstruction of tracks associated to charged particles traversing the tracking chamber is a two step procedure:

flr_track_fit.png
Track fitting procedure applied to calibrated events

We create a new rec.conf script with a custom pipeline inline module made of five consecutive modules. The first two perform the mock calibration as shown in the previous section. Then we use a new module CATTrackerClusterizer to run the clustering algorithm, followed by the TrackFitting module to run the line/helix fitting on the found clusters. As before, we add a dump module at the end of the pipeline to print each event to standard output.

As we now use modules implemented by dedicated Falaise plugins, we must explicitly provide a flreconstruct.plugins section with the list of plugins that must be dynamically loaded to allow the pipeline to work:

#@key_label "name"
#@meta_label "type"
[name="flreconstruct.plugins" type="flreconstruct::section"]
plugins : string[3] = "Falaise_CAT" \
"TrackFit" \
"Falaise_TrackFit"
[name="pipeline" type="dpp::chain_module"]
modules : string[5] = \
"CalibrateTracker" \
"CalibrateCalorimeters" \
"CATTrackerClusterizer" \
"TrackFitting" \
"Dump"
[name="CalibrateTracker" type="snemo::processing::mock_tracker_s2c_module"]
[name="CalibrateCalorimeters" type="snemo::processing::mock_calorimeter_s2c_module"]
[name="CATTrackerClusterizer" type="snemo::reconstruction::cat_tracker_clustering_module"]
TPC.processing_prompt_hits : boolean = true
TPC.processing_delayed_hits : boolean = false
[name="TrackFitting" type="snemo::reconstruction::trackfit_tracker_fitting_module"]
fitting_models : string[2] = "helix" "line"
line.only_guess : string[4] = "BB" "BT" "TB" "TT"
helix.only_guess : string[8] = "BBB" "BBT" "BTB" "BTT" "TBB" "TBT" "TTB" "TTT"
[name="Dump" type="dpp::dump_module"]

We run:

$ flreconstruct -i example.brio -p rec.conf -o example-rec.brio
[notice:void datatools::library_loader::init():449] Automatic loading of library 'Falaise_CAT'...
[notice:void datatools::library_loader::init():449] Automatic loading of library 'TrackFit'...
[notice:void datatools::library_loader::init():449] Automatic loading of library 'Falaise_TrackFit'...
...
|-- Bank 'CD' : "snemo::datamodel::calibrated_data"
: ...
|-- Bank 'SD' : "mctools::simulated_data"
: ...
|-- Bank 'TCD' : "snemo::datamodel::tracker_clustering_data"
: ...
`-- Bank 'TTD' : "snemo::datamodel::tracker_trajectory_data"
...

Now two banks have been added in the event records:

The display shows the best found clusterization/fitting solutions with two clusters of tracker hits (red and blue) and the best associated tracks that have been computed from these clusters. We clearly recognize a two electrons event pattern, but here only one is associated to a calorimeter block.

flr_qs_trackfit_event.png
A simulated event with reconstructed tracker clusters and fitted tracks

To do

Document more reconstruction steps:

Supported sections and parameters in FLReconstruct scripts

The FLReconstruct script contains up to five sections of type flreconstruct::section with the following names:

A sample configuration script showing the organisation of the above parameters is shown below. Note that many of the parameters are commented out as they are generally note needed except for advanced use or testing.

# Author: F. Mauger <mauger@lpccaen.in2p3.fr>
# Date: 2017-03-27
# Format: datatools::multi_properties
# Description: Sample configuration script for flreconstruct (Falaise 3.0.0)
# Supports: SuperNEMO Demonstrator Reconstruction setup using version 1.0.0 of the pipeline
#@description Sample SuperNEMO Demonstrator Reconstruction Pipeline
#@key_label "name"
#@meta_label "type"
####################################################
[name="flreconstruct" type="flreconstruct::section"]
#@config Basic setup
# #@description Reconstruction version (automatic: extracted from input metadata)
# experimentalSetupUrn : string = "urn:snemo:demonstrator:setup:1.0"
# #@description Number of events to reconstruct (default: 0 = no limit)
# numberOfEvents : integer = 0
###################################################################
[name="flreconstruct.variantService" type="flreconstruct::section"]
#@config Variant setup
# #@description Variant configuration URN (automatic: extracted from 'experimentalSetupUrn')
# configUrn : string as path = "urn:snemo:demonstrator:setup:1.0:variants"
# #@description Variant configuration (automatic: resolved from 'configUrn')
# config : string as path = "@falaise:config/snemo/demonstrator/setup/1.0/variants/repository.conf"
# #@description Input variant profile configuration file (automatic: default from 'configUrn')
# profileUrn : string = "urn:snemo:demonstrator:setup:1.0:variants:profiles:default"
# #@description Input variant profile configuration file (automatic: resolved from 'profileUrn')
# profile : string as path = "@falaise:config/snemo/demonstrator/geometry/4.0/variants/profiles/basic-1.0.0.profile"
#############################################################
[name="flreconstruct.services" type="flreconstruct::section"]
#@config Services setup
# #@description Service manager configuration URN (automatic: extracted from 'experimentalSetupUrn')
# configUrn : string = "urn:snemo:demonstrator:setup:1.0:services"
# #@description Service manager configuration file (automatic: resolved from 'configUrn')
# config : string as path = "@falaise:config/snemo/demonstrator/setup/1.0/services.conf"
############################################################
[name="flreconstruct.plugins" type="flreconstruct::section"]
#@config Plugin managment
#@description The list of plugins
plugins : string[4] = "Falaise_CAT" \
"TrackFit" \
"Falaise_TrackFit" \
"Falaise_ChargedParticleTracking"
# Adapt this path to the location of Falaise_ChargedParticleTracking if needed.
# Default path for Falaise plugins is "@falaise.plugins:"
# #@description The path from where to load the Falaise_ChargedParticleTracking plugin
# Falaise_ChargedParticleTracking.directory : string = "@falaise.plugins:"
#############################################################
[name="flreconstruct.pipeline" type="flreconstruct::section"]
#@config Pipeline modules configuration
#@description Tag of the reconstruction (registered)
configUrn : string = "urn:snemo:demonstrator:reconstruction:1.0.0:pipeline"
# #@description File containing a list of modules for the pipeline (automatically resolved)
# config : string as path = "@falaise:config/snemo/demonstrator/reconstruction/pipeline/1.0.0/modules.defs"
# # Can also be set manually to a local file:
# config : string as path = "pipeline_modules.defs"
# #@description The name of the top module in the pipeline (default="pipeline")
# module : string = "pipeline"
# end

The majority of scripts will just use the flreconstruct.plugins and flreconstruct.pipeline sections to select from the set of plugins and pipelines approved by the Calibration and Reconstruction Working Group. Output results from these can be used in the preparation of analyses.

Inline modules

In the case the flreconstruct.pipeline section does not define an explicit pipeline configuration by tag (configUrn) or configuration file path (config), it is possible to provide a list of additional sections which define reconstruction modules. This technique is named the inline pipeline mode. Such a section uses the following format:

[name="ModuleName" type="ModuleType"]
... module's configuration parameters ...

where ModuleName is the unique name of the module and ModuleType is the identifier of its registered class type (see below).

This mode should not be used for production runs. It is expected that only official registered pipeline setups are used in such a case, through the configUrn properties in the flreconstruct.pipeline section.

Using Standard Pipelines

FLReconstruct implements a "pipeline" architecture in which events flow through an ordered sequence of "modules". Each module performs a specific task on the event (e.g. count hits), writing its results into the event for further processing by downstream modules. The sequence of modules and their configuration (e.g. algorithm parameters) in the pipeline are constructed via a datatools::multi_properties script. A set of pipeline scripts are supplied with Falaise by the Software Board to provide easy to use, validated reconstruction chains.

The available pipelines can be viewed by passing the --help-pipeline-list argument to flreconstruct. This will print a list of the available builtin pipelines

$ flreconstruct --help-pipeline-list
List of supported reconstruction pipeline:
urn:snemo:demonstrator:reconstruction:1.0.0:pipeline : Processing pipeline modules for the SuperNEMO reconstruction setup (version 1.0.0)
urn:snemo:demonstrator:reconstruction:hc-1.0.0:pipeline : Processing pipeline modules for the SuperNEMO reconstruction setup (Half-Commissioning version 1.0.0)
$

In order to use a official registered pipeline, one shoud use:

[name="flreconstruct.pipeline" type="flreconstruct::section"]
configUrn : string = PIPELINE_TAG

where PIPELINE_TAG is the release tag of a reconstruction pipeline. Example with the official pipeline with tag "urn:snemo:demonstrator:reconstruction:1.0.0:pipeline":

[name="flreconstruct.plugins" type="flreconstruct::section"]
plugins : string[4] = "Falaise_CAT" \
"TrackFit" \
"Falaise_TrackFit" \
"Falaise_ChargedParticleTracking"
[name="flreconstruct.pipeline" type="flreconstruct::section"]
configUrn : string = "urn:snemo:demonstrator:reconstruction:1.0.0:pipeline"

Standard pipeline scripts are organised into directories based on the experiment they apply to, and should only be used for reconstructing data from these experiments. Note that flreconstruct tries to validate that a pipeline script can be applied to the input data. Pipeline definition scripts for each experiments are tagged with a versioning URN. You should always consider carefully which version tag to use for production and check its compatibility with the process which has generated input data (i.e. the FLSimulate setup).

The output file generated by flreconstruct may be opened and the results visualized using the `flvisualize` GUI application

Builtin reconstruction scripts can be run in flreconstruct:

$ flreconstruct -i example.brio -p myrecscript.conf

If standard reconstruction scripts are published in Falaise, it is possible to use the following syntax:

$ flreconstruct -i example.brio -p @falaise:config/snemo/demonstrator/reconstruction/pipeline/1.0.0/flreconstruct.conf

Here @falaise: is simply shorthand for "the root directory of standard Falaise resources" and can be viewed as a "mount point" for standard resource files. The subsequent path is simply the path from that root to the standard reconstruction script.

If the script itself is officially tagged, one can also use directly its tag from the command line:

$ flreconstruct -i example.brio -p "urn:snemo:demonstrator:reconstruction:1.0.0"

Note here that the FLreconstruct script tagged "urn:snemo:demonstrator:reconstruction:1.0.0" is based on the reconstruction pipeline tagged "urn:snemo:demonstrator:reconstruction:1.0.0:pipeline". The dependency scheme associated to this specific FLReconstruct script is:

+-- urn:snemo:demonstrator:reconstruction:1.0.0 (reconstruction script)
+-- urn:snemo:demonstrator:setup:1.0 (related experimental setup)
+-- urn:snemo:demonstrator:setup:1.0:services
| +-- urn:snemo:demonstrator:geometry:4.0 (used geometry model)
+-- urn:snemo:demonstrator:setup:1.0:variants (used variant configuration)
+-- urn:snemo:demonstrator:setup:1.0:variants:profiles:basic-1.0.0 (variant profile is fixed)
+-- urn:snemo:demonstrator:reconstruction:1.0.0:pipeline (reconstruction pipeline)

We can see that choosing the top-level script implies to fix all configuration of all components used by the software.

Writing Reconstruction Results to File

To write flreconstruct's results to file (e.g. for later analysis), the -o option may be used to write processed events to a file supplied as the argument, with the output format chosen based on the file extension.

To output to the BRIO format recognised by flreconstruct use the .brio extension:

$ flreconstruct -i example.brio -p myrecscript.conf -o results.brio

The resultant file may be examined directly to see what data has been written by simply passing it back to flreconstruct, e.g.

$ flreconstruct -i results.brio
... output ...

The resultant file may also be further processed by flreconstruct using a pipeline constructed from your own analysis modules. Please see the document on FLReconstruct Pipeline Output for details of the data structures stored for each processed event. Further documents are available detailing how to write your reconstruction/analysis modules, and how to access event data from modules.

Output to ROOT format is also possible by supplying an output file with the .root extension:

$ flreconstruct -i example.brio -p myrecscript.conf -o results.root

The resultant file contains a single flat TTree structure that may be browsed interactively. Note that currently this format only outputs simulated and calibrated data, with no further reconstruction results. A separate converter program is available for running full conversion, and will be gradually integrated into flreconstruct for direct conversion.

Using Custom Pipelines

The standard pipelines provided by Falaise are intended to cover a wide range of use cases for standard reconstruction tasks leading to analyses. However, if you need to study improvements to the reconstruction via tuning existing modules or adding new ones then custom pipeline scripts and modules can be used in flreconstruct. The Writing FLReconstruct Pipeline Scripts tutorial covers the syntax and structure of custom pipeline scripts.