Simulation, Reconstruction and Analysis for the SuperNEMO Experiment
Clone or download
Latest commit 38d67f7 Nov 13, 2018

README.md

Falaise C++ Library and Applications for the SuperNEMO experiment

Build Status

Falaise provides the main computational environment for the simulation, processing and analysis of data for the SuperNEMO double beta decay search experiment. The three main components are

  • libFalaise: the core library.

  • flsimulate: the main detector simulation application.

  • flreconstruct: the main reconstruction application.

A pipeline architecture is used in which the pipeline stages may be configured and added to at runtime via a plugin system. Code for pipeline stages is stored in the modules subdirectory with each module (or set of modules) having its own directory.

Additional modules from external sources and individual contribution can be used too.

Installing Falaise

Quickstart

If you simply wish to use or try out Falaise, we recommend installing it using our Home/Linuxbrew tap. This will install everything you need, and includes the latest official release of the software.

Once installed, consult the online documentation for a full guide to running the software and writing new plugin modules.

If you have Docker available, then images for current and past releases together with instructions for use are available from Docker Hub.

Building, Testing and Installing from Source

To build Falaise on your machine, the following requirements must be met:

  • Linux or macOS System
    • Supported Linux systems: CentOS6/7, Ubuntu 14.04/16.04LTS
    • Other Linux distributions are known to work, but are not officially supported. However, patches are welcome to resolve encountered issues!
    • Suported macOS systems: 10.10/11/12 (Mavericks/El Capitan/Sierra)
    • macOS High Sierra is not yet officially supported, but work is in progress
  • GCC (>= 4.9), Clang (>=3.5) or Xcode 7/8
  • CMake 3.5 or higher
  • Doxygen 1.8 or higher
  • Bayeux 3.1.2 or higher
  • Boost 1.63.0 or higher
    • Must provide program_options, thread, serialization, filesystem and system components
  • Camp 0.7.1 or higher
  • GSL 1.16 or higher
  • CLHEP 2.1.3.1 or higher
  • Geant4 9.6.4 or higher
    • with GDML support enabled
  • ROOT 6.10 or higher

Falaise requires use of the C++11 or higher standard, so all of the above packages and their C++ dependencies must be built/installed using this standard. This is to ensure binary compatibility.

To get the source code, either download a release tarball or to get the latest development, do

$ git clone https://github.com/supernemo-dbd/Falaise.git Falaise.git

To build Falaise, do

$ mkdir Falaise.build
$ cd Falaise.build
$ cmake -DCMAKE_INSTALL_PREFIX=/where/you/want/to/install ../Falaise.git
...

If you wish to enable make test after building, add the following option to cmake.

$ cmake -DFALAISE_ENABLE_TESTING=ON

Note: At this stage, if the following error is encountered;

  CMake Error at /home/<user>/CadfaelBrew/lib64/cmake/Bayeux-3.1.2/BayeuxConfig.cmake:130 (find_package):
  By not providing "FindQt5Core.cmake" in CMAKE_MODULE_PATH this project has
   asked CMake to find a package configuration file provided by "Qt5Core", but
  CMake did not find one.

  Could not find a package configuration file provided by "Qt5Core"
   (requested version 5.8.0) with any of the following names:

    Qt5CoreConfig.cmake
    qt5core-config.cmake

  ..

add the following options to the cmake command.

$ cmake -DCMAKE_PREFIX_PATH="$(brew --prefix);$(brew --prefix qt5-base)" <other options follow>

More info regarding Qt5Core and Falaise can be found at this address: (https://github.com/Homebrew/homebrew-core/issues/8392)

Errors at this stage are likely to be due to missing/unfound packages. If this is the case, cmake can be directed to look in specific places using the CMAKE_PREFIX_PATH variable. For example, if Boost is installed in $HOME/boost and GSL in $HOME/software/gsl, cmake would be run as:

$ cmake -DCMAKE_PREFIX_PATH="$HOME/boost;$HOME/software/gsl" -DCMAKE_INSTALL_PREFIX=/some/path ../Falaise.git

The CMAKE_INSTALL_PREFIX variable tells CMake where the products of the build should be installed. Ensure you have write permissions to this location.

After configuration is successful, the build is run by:

$ make -j<N>

Adjust <N> to the number of cores on your machine for a faster build. After a successful build, unit tests can be run using the test target:

$ make test

On completion of the build, the Falaise programs, libraries and documentation are available for use under a POSIX-style hierarchy under the BuildProducts subdirectory of the directory in which you ran the build. For example,

$ ./BuildProducts/bin/flsimulate --help

Documentation for the build is viewable by opening the main page in your browser. On macOS, the open command can be used:

$ open ./BuildProducts/share/Falaise-<VERSION>/Documentation/API/html/index.html

where <VERSION> is the current Falaise version (simply use tab-complete if you are unsure of this) which should open a new tab in your browser populated with the documentation frontpage. On Linux, you can generally do the same by running

$ xdg-open ./BuildProducts/share/Falaise-<VERSION>/Documentation/API/html/index.html

though xdg-open may not always be present (gnome-open may be used instead, for example).

If you need to install Falaise, you can run

$ make install

to install everything in a standard POSIX style hierarchy under the directory passed as CMAKE_INSTALL_PREFIX.

Getting Help

If you have problems, questions, ideas or suggestions on Falaise or any of its submodules, raise an issue.

Contributing to Falaise

Please see the Contribution Guide

Naming

Falaise is named thus because Falaise is the town in Normandy where William the Conqueror was born. Note this has nothing to do with SuperNEMO software!

Licensing

Please study the file LICENSE.txt for the distribution terms and conditions of use of Falaise.

Contributors

Many thanks go to Falaise's contributors