Event Formation Unit

This project implements processing of neutron detector event data into neutron events. Pipelines for processing of raw data from Gd-GEM, Muli-Grid, Multi-Blade, SoNDe as well as a few other detectors have been implemented. Mostly implemented in C/C++.

Documentation

For more details on the file structure, architecture, primitives see documentation/README.md

Changelog Generator

This project includes an automated changelog generator that creates formatted release notes from git commits. The tool uses uv for dependency management and requires no manual setup. See utils/changelog/README.md for details.

Quick usage from project root:

# Generate changelog since last tag (recommended)
./generate-changelog.sh --from-commit v1.0.0

# Or run directly with uv
uv run utils/changelog/generate_changelog.py --from-commit abc1234 --times

# Script can also be run directly (with executable permissions)
utils/changelog/generate_changelog.py --from-commit abc1234

Getting started

The essdaq repository has scripts for automatically downloading and compiling this project. Instructions for manually compiling the event formation unit software follow.

Prerequisites

To build and run this software the following dependencies are required.

• Conan The conan script has to be available in the current $PATH. Use the latest version smaller than 2.
• CMake At least CMake version 2.8.12 is required. Some packages that requires more recent versions of CMake will download this as a dependency.
• bash For properly setting paths to the conan provided dependencies.
• A recent C/C++ compiler with support for C++14.

Note also that for additional functionality, you might want to install the following dependencies manually:

• libpcap —Network monitoring
• Valgrind — Memory usage (and other) tests
• gcovr, lcov, and gcov — Generate coverage reports

Install and Configure Conan

1. Create and activate a virtual environment

python3 -m venv venv
source venv/bin/activate

2. Install Conan (version < 2)

pip install "conan<2"

3. Verify Conan installation

conan --version

4. Install the Conan configuration

This includes supported Conan profiles and access to the ECDC internal package repository:

conan config install http://github.com/ess-dmsc/conan-configuration.git

Release Build

1. Create a build directory:

mkdir build && cd build

2. Install Dependencies with Conan

The ECDC Conan configuration includes a predefined profile: linux_x86_64_gcc11. This profile is well-tested and has many prebuilt binaries available in our remote repository. It's also the one we use in automated ci builds for this project.

If you're working on a different architecture (e.g. Apple Silicon) or using a different compiler (e.g. GCC 13), note that no predefined profiles exist in our config for those setups. In such cases, you'll need to use Conan's locally generated default profile.

Verify your default profile exists:

conan profile show default

To install dependencies using your local profile:

conan install .. --build=missing

To use the ECDC-supported Linux x86 GCC 11 profile instead, add:

--profile=linux_x86_64_gcc11

3. Configure the project with CMake:

cmake .. -DCMAKE_BUILD_TYPE=Release

4. Build the project:

make -j$(nproc)

Debug build for unit tests and coverage

1. Create a build directory:

mkdir build && cd build

2. Install dependencies with Conan:

conan install .. --build=missing -s build_type=Debug

3. Configure the project with CMake:

cmake -DCOV=ON -DCMAKE_BUILD_TYPE=Debug -DGOOGLE_BENCHMARK=ON ..

4. Run unit tests:

make runtest

5. Generate coverage report:

make coverage_all

View the report:

open coverage/coverage.html

6. To run a memory leak test, run:

make valgrind

Building Doxygen docmentation

Doxygen documentation for the EFU C++ classes can be build by running

make doxygen

After the documentation has been build, the doxygen documentation tree can be accesed in the cmake build directory, by opening the file doxygen/html/index.html.

Running the event formation application

An example of the commands required to run an event formation pipeline (in this case the freia pipeline) follows:

make efu freia
cd bin
./efu -d ../modules/freia --nohwcheck

Note you will need to provide a config file in the case of the freia module as well.

To get the available command line arguments, use -h or --help. This works when providing a detector module argument as well. For example:

./efu -d ../modules/freia -h

Contributing

Please read the CONTRIBUTING.md file for details on our code of conduct and the process for submitting pull requests to us.

Authors

• Morten Jagd Christensen
• Martin Shetty
• Jonas Nilsson
• Jenny Walker

See also the list of contributors on Github.

License

This project is licensed under the BSD-2 License see the LICENSE file for details.