Skip to content

An introduction to LHCb Software

Learning Objectives

  • Learn the key concepts needed to work with the LHCb software
  • Learn how to launch the LHCb software with lb-run and lbexec

Imagine you want to design and run a new particle detector. Apart from organizing a collaboration, creating the design and specification, and several other tasks, you will also have to find solutions to many computational challenges. It's worth thinking about these for a second:

  • How do we collect data as it is recorded by the detector?
  • How do we filter and process the recorded data efficiently?
  • How do we manage all the complex tasks required to work with collision data?
  • How do we organize all the data of a single bunch crossing in a flexible way?
  • How do we configure our software flexibly without having to recompile it?
  • Can you think of more?

How would you go about solving these? The decisions you make will affect the performance of your experiment during datataking and analysis.

At LHCb, we base most of our software on the Gaudi framework, which was specifically designed with the above questions in mind. It's worth getting an idea of some of the most important Gaudi concepts at this point. After this, we will jump right into running the software and getting useful things done.

Event Loop: Because the individual bunch crossings (events) are almost completely independent of each other, it makes sense to process them one by one, without holding them all in memory at once. Gaudi provides a global EventLoop, which allows you to process events one by one.

Transient Event Store: A single event contains lots of different data objects (Particles, Vertices, Tracks, Hits). In Gaudi, these are organized in the Transient Event Store (TES). You can think of it as a per-event file system with locations like /Event/Rec/Track/Best or /Event/Phys/MyParticles. When running over the event stream, Gaudi allows you to get and put from/to these locations. The contents of the TES are emptied at the end of the processing of each event.

Algorithms: An Algorithm is a C++ class that can be inserted into the EventLoop. These allow you to perform a certain function for each event (like filtering according to trigger decision, reconstructing particles).

Tools: Often, algorithms will want to make use of some common function (vertex fitting, calculating distances, associating a primary vertex). These are implemented as Tools, which are shared between Algorithms.

Options: To make all of this configurable, Gaudi allows you to set properties of Algorithms and Tools from a Python script, called an option file. In an option file, you can specify which Algorithms are run in which order, and set their properties (strings, integers, doubles, and lists and dicts of these things can be set). You can then start the Gaudi EventLoop using this option file, and it will set up and run the corresponding C++ objects with specified settings.

You can find comprehensive documentation in the Gaudi Doxygen or the Gaudi Manual.

Usually, you will work with one of the LHCb software projects that are based on Gaudi. One of the most important ones is DaVinci, which provides lots of Algorithms and Tools for physics analysis as well as being the key way of converting LHCb data into nTuples.

You can run DaVinci using the following command on lxplus: 

lb-run DaVinci/v65r0 lbexec --help

This will run the lbexec command using version v65r0 of DaVinci. (lb-run sets the specified environment for lbexec to run in.) You should get the following output:

usage: lbexec [-h] [--dry-run] [--export EXPORT] [--with-defaults] [--override-option-class OVERRIDE_OPTION_CLASS] function options [extra_args ...]

positional arguments:
  function              Function to call with the options that will return the configuration. Given in the form 'my_module:function_name'.
  options               YAML data to populate the Application.Options object with. Multiple files can merged using 'file1.yaml+file2.yaml'.
  extra_args

optional arguments:
  -h, --help            show this help message and exit
  --dry-run             Do not run the application, just generate the configuration.
  --export EXPORT       Write a file containing the full options (use "-" for stdout)
  --with-defaults       Include options set to default values (for use with --export)
  --override-option-class OVERRIDE_OPTION_CLASS
                        Allows to override the option class specified in the function signature.Given in the form 'my_module:ClassName'.

During this run, DaVinci didn't do anything: We didn't specify any algorithms to run or any data to run over. Usually, you will give two arguments:

  • An function to run, written in python, from which lbexec will start running code
  • An configuration file, written in yaml, defining the conditions

The syntax to then run DaVinci with these two files will be:

lb-run DaVinci/v65r0 lbexec script.py:main config.yaml

Do you want to get an overview of which versions of DaVinci exist? Use 

lb-run --list DaVinci

Which version of DaVinci should I use?

All available versions of DaVinci are given on the DaVinci releases page. Which one should you use? There are a couple of guidelines to follow:

  1. When starting a new analysis, use the latest version suitable for the data you would like to analyse.
  2. When continuing an analysis, use the same version of DaVinci consistently throughout. This includes cases where you want to repeat an existing analysis but with modified settings, e.g. re-running a Stripping line.

There are a set of DaVinci versions for Run 3 (versions v50r1 and above) and a set for everything else. Generally, you will want the latest version in the latter set.

These lessons use DaVinci v65r0, which was the latest Run 3 version at the time the text was last revised.

Note: Older versions of DaVinci may not be available on the default platform x86_64_v3-el9-gcc13-opt+g. To get around this we can pick the best suitable platform by using lb-run -c best DaVinci/vXXrYpZ .... More details about the platform string are available in HSF-TN-2018-01.

Do you want to start a shell that already contains the LHCb environment, so you don't have to use lb-run? Execute 

lb-run DaVinci/v65r0 $SHELL
Note that sometimes this environment can result in failing scripts due to struggles with your shell's rc file (e.g., ~/.bashrc). Using 
lb-run DaVinci/v65r0 bash --norc
avoids this, but means you won't be able to use any aliases, etc, included in the ignored rc file.

From here, an lbexec command may be used, as above, but without the prepended arguments i.e.

lbexec script.py:main config.yaml

Typing exit or using Ctrl-d will close the shell and leave the LHCb environment behind.

Using gaudirun.py

Using lbexec is the modern way of running Gaudi applications, however there is an older way you may sometimes see: This is using the python script gaudirun.py. gaudirun.py accepts your algorithm as a python file as before, but also accepts the configuration options as a separate python file instead of yaml.

For details on how to use gaudirun.py you may reference the Run 2 starterkit's LHCb Software and DaVinci lessons.