Falaise C++ Library and Applications for the SuperNEMO experiment

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.

• flvisualize: the event/detector geometry display application

A pipeline architecture is used for flreconstruct 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 and Using Falaise

If you are using Falaise, i.e. running the applications to generate, process, and analyse data, then you only require an install of Falaise. If you need to develop Falaise, i.e. make changes to the code to fix issues or add new features, please see Developing and Testing Falaise below.

We recommend installing Falaise and its requirements as documented on our fork of Homebrew. By default this will install the latest stable release of Falaise. All releases with details of the changes introduced are listed on the GitHub Releases page. For production and general work, you should only use a stable release (i.e. a git tag using a version number such as v4.0.3). These are not guaranteed to be bug free, but have passed all known/implemented tests at the time of their release (i.e. no known bugs at that time), with physics related features validated to the same level.

Docker/Singularity Image installs are also available, both providing a complete suite of software and tools for using and developing Falaise and extension modules. We strongly recommend Docker/Singularity Images on systems which support these tools, especially on institution systems/clusters such as CC-IN2P3, as they provide the most reliable and reproducible Falaise installs.

For both native image installs we strongly recommend that you run the Falaise applications from within the snemo-shell shell environment provided, which is started and exited by running:

$ brew snemo-shell
Homebrew >=1.7.1 (shallow or no git repository)
Supernemo-dbd/homebrew-core (git revision 15b2f; last commit 2019-02-27)
Type "brew ls --versions" to list available software
Type "exit" to deactivate the session
snemo-shell> flsimulate --version
...
snemo-shell> exit
$

Once installed and setup, consult the online documentation for a full guide to running flsimulate, flreconstruct, and writing your own plugin modules.

Building and Testing Falaise

If you wish to develop Falaise, e.g. find and fix a bug, or add new functionality, then you will need to get the Falaise source code and build and test it yourself. The first step here is to install of the tools and libraries needed to build and test Falaise. The aforementioned SuperNEMO Homebrew installer or Docker/Singularity installers can be used here for simplicity as they provide an install of all the needed software for development. You can also install the full list of prerequisites using the package manager of your choice:

• Linux or macOS Operating System
  • Supported Linux systems: CentOS7, Ubuntu 20.04LTS
  • Other Linux distributions are known to work, but are not supported
  • Supported macOS systems: 10.14/15 (Mojave, Catalina)
• GCC (>= 7), Clang (>=6) or Xcode >= 10
• Git
• CMake 3.12 or higher
• Doxygen 1.8 or higher
• Bayeux 3.4.1 or higher
• Boost 1.69.0 only
  • Must provide program_options, thread, serialization, filesystem and system components
• Camp 0.7.1 or higher
• GSL 2 or higher
• CLHEP 2.1.3.1 only
• Geant4 9.6.4 only
  • with GDML support enabled
• ROOT 6.16 or higher

With these in place, to get set up on your local system to develop Falaise you should then:

1. Create your own Fork of the SuperNEMO-DBD/Falaise repository on GitHub
2. Clone your Fork to your local system
3. Build and test Falaise
4. Start developing and testing on a Topic Branch
5. Submit your Topic Branch to SuperNEMO-DBD/Falaise as a Pull Request

Please see CONTRIBUTING.md for comprehensive guides and cheatsheets on this workflow. Here, we will quickly demonstrate steps 2 and 3.

To get the source code from your Fork of Falaise locally, simply clone it:

$ git clone https://github.com/<yourgithubid>/Falaise.git Falaise.git

With the source code cloned, it can be configured and compiled by doing:

$ mkdir Falaise.build
$ cd Falaise.build
$ cmake -DFALAISE_ENABLE_TESTING=ON ../Falaise.git

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" -DFALAISE_ENABLE_TESTING=ON ../Falaise.git

After configuration is successful, the build is run by:

$ make -jN

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

$ ctest -jN

This will run the tests in parallel and provide a summary report of successes and failures. You can see full output from the tests, e.g. to check failures, by doing

$ ctest -jN -VV

See man ctest for further options.

On completion of the build, the Falaise programs, libraries and documentation are available for direct 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 is browsable 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).

The above only covers the basics of creating a local development setup, and you should consult the full CONTRIBUTING.md for details of the development, testing and Pull Request submission process.

Stability of the develop branch

Please note that builds like the above must not be used for production or analysis work. The develop branch that provides the foundation for new developments is used only to integrate fixes and new functionality. Whilst it is tested to the same level as releases through the Pull Request process, the development cycle may introduce new and as-yet unidentified bugs.

Getting Help

If you have problems, questions, ideas or suggestions on Falaise or any of its submodules, just raise this on the project board.

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