Histogram BRILDAQ software

During Phase 2 of the LHC, the CMS BRIL subsystem will attempt to resolve luminosity by histogramming luminosity observables from other CMS front-ends. This Twiki collects the documentation for the BRILDAQ software used for reading and processing the histogrammed output from non-BRIL subdetectors, like the DT system and/or the Scouting system. It is also a guide for anyone wishing to contribute to the development of this software. Currently (October 2022), only a DT demonstrator source and a simple version of a DT processor have been implemented. They will be described below. Information that is common for the development of similar applications has been extracted/copied from the PLTBRILDAQSoftware documentation, which is a good reference.

General BRILDAQ and XDAQ concepts

XDAQ software is based on the event-driven paradigm. In this sense, it works a lot different than other CMS software, like CMSSW. BRILDAQ experts have written good tutorials that can be found in the BRILDAQ Work Book. The most recent training sessions (September 2021), with video recordings, can be found on Indico.

Make sure you get familiar with the material covered by these tutorials before attempting to contribute to the development effort. Be advised, however, that many of the concepts and xdaq objects only become apparent when trying do make actual improvements and/or add new features to the software.

Software location

The BRILDAQ software is a part of the cmsos repository and can be found on gitlab. IMPORTANT: Make sure to always look at the correct baseline branch (currently baseline_kiwi_2 for xdaq15, but make sure that you are looking at the newest baseline branch). Within the bril/ directory, there is one directory for each BRILDAQ application (generally corresponding to each subsystem). The main source code for the application is in folders similar to src/common/Application.cc, and the corresponding header file is found in places similar to include/bril/[application name]/Application.h.

In addition to the files making up each application, you should also be aware of the files that define the data passed between applications. These are in interface/bril/include/interface/bril/; the [Application]Topics.hh file defines the data published by each application (or group of applications; for example, HistogramGenericTopics.hh). See chapter 5 of the workbook above for more details on how these topics are defined, but the examples should make it pretty clear.

Topics

In the cmsos bril repository, under interface/bril/include/interface/bril, there are header files that describe the way in which histogram information is encoded for each sub-detector and the structure of the output products for the BRILDAQ applications. These descriptions are known as topics and are widely used in order to map the software input and output.

Procedure for making changes

Because the BRILDAQ software is part of the cmsos repository, there is a strict procedure for making and submitting changes:

1. Make sure you're on the correct branch to base your changes from (baseline_kiwi_2 as of the writing of this document, but changes may occur!)
2. Create a gitlab issue for tracking the issue, including a description.
3. Create a git branch named "feature_[issue number]".
4. Develop your changes.
5. Make sure that you increment the version number in include/bril/[application name]/version.h; this is necessary in order to build the rpm with the new version.
6. Commit your changes with the comment of the form "references #[issue number]: [your comments]". If the commit message is not in this format, your attempt to push will be automatically rejected!
7. Push your branch and create a merge request.

These steps are all summarized in this document.

Compiling changes

In order to compile your application, you will need you have your environment set up properly. You can do this for xdaq15 with source ~xiezhen/devsetenv.sh. Note that the environments for compiling and running (see below) are not compatible! Once your environment is set up, you can use the Makefile within your application directory to compile. (Don't use the top-level Makefile unless you really want to compile everything and have a few spare hours.) See Zhen's tutorial page for more information on setting up your environment.

General Histogram BRILDAQ software approach

Since the histogrammed output from the different CMS front-ends that will be delivering data to BRIL share similar features, the BRILDAQ software for reading (source) and processing (processor) these data will have a common baseline code called generic and additional code, which will be specific to the peculiarities of each detector.

Currently the Histogram BRILDAQ software has two applications:

• the /bril/bril/histogramsource application under the cmsos/bril repository, which deals with picking up the output from the histogramming modules from a given CMS front-end and
• the /bril/bril/histotramprocessor application under the cosos/bril repository, which gets the output from the source and performs luminosity calculations and deliver other needed products.

These two applications have a package called generic, where the baseline code common to all subdetectors is stored, and a specific detector-dependent package, where additional or complementary software is developed if needed. An example of the latter is the current dtdemo package.

Anyone willing to contribute to the development of these packages should adopt this strategy. I.e., use or improve the general baseline code and, only when needed, develop code for the specific features of each sub-detector.

Generic histogram packages

As mentioned above, the histogram BRILDAQ software has a baseline code that is common to all CMS front-ends contributing to BRIL luminosity. Here we briefly describe this code in its two flavors, the source code and the processor code.

Generic histogram source

The generic histogram source package can be found in the cmsos bril repository under bril/bril/histogramsource/generic. The purpose of this application is to listen to the output of the histogramming (firmware) modules from the different CMS front-end clients and publish it to the BRILDAQ data bus. For this, it makes use of a general ReadoutInterface class that manages two kinds of input interfaces depending on the nature of the client hardware: the = IpbusInterface= and the SimpleTcpInterface. There is an additional interface that is being developed, the DummyInterface, which allows for testing of the source code without an actual input from hardware. Details can be seen below.

The application also makes sure the input from the front-end is in synch with the TCDS information from CMS, that there are no duplicate o missed histograms, and that lumi sections and lumi nibbles are aligned.

The DummyInterface

The DummyInterface is an additional interface to the histogram source code that allows a user to test the code without having to listen to the actual hardware. The code is currently only available in a private fork of the cmsos bril repository.

Generic histogram processor

The generic histogram processor package can be found in the cmsos bril repository under bril/bril/histogramprocessor/generic. The purpose of the generic histogram processor is to listen to the publication of the source, perform certain calculations and deliver products like average calibrated or non-calibrated per-bunch luminosity, per channel luminosity, etc. The current version of the processor is limited. It plots raw and averaged histogram counts on a web application but does not perform detailed calculations nor publish to the BRILDAQ bus. Development on the generic processor is ongoing in a private fork of the cmsos bril repository.

DT Demo

The pilot system for testing the histogram BRILDAQ software is the DT demonstrator. The DT demonstrator, which is currently available in Run 3, reads histograms of muon track segments from a slice of the Muon Barrel system (DT system). It consists of the source and the processor code, which builds on top of the generic baseline described above.

DT Demo source

The DT Demo histogram source package can be found in the cmsos bril repository under bril/bril/histogramsource/dtdemo. The code complements the generic source code described above by assigning the adequate topics for this subsystem. The xml configuration file for this demonstrator resides in bril/histogramsource/dtdemo/xml/histogramsourcedtdemo.xml. This configurator is usually run on the online machine srv-s2d16-15-01 (also aliased to dtdemolumi). However, for the moment one should avoid running the source on this machine since developers are still working on it.

DT Demo processor

The DT Demo histogram source package can be found in the cmsos bril repository under bril/bril/histogramprocessor/dtdemo. The code complements the generic processor code described above by assigning the adequate topics for this subsystem. It is currently under development.

Running the DT Demo processor with the DummyInterface

In order to test the DT Demo processor without the real source, one can use the DummyInterface described above. After cloning this private fork, one could run the histogramdummyprocessordtdemo.xml configurator, mimicking the DT source input. Executing should look something like:

 /opt/xdaq/bin/xdaq.exe -p 50000 -z bril -c /nfshome0/ecarrera/brildaq/bril/bril/histogramprocessor/dtdemo/xml/histogramdummyprocessordtdemo.xml

-- EdgarCarrera - 2022-06-15