Ucesb Unpacker Stage

Using ucesb as unpacker stage for R3BROOT

The versatile unpacker generator ucesb can be used as unpacking stage for R3BROOT. This allows the user to write the unpacker using a human-readable specification, rather than in C/C++ code. Thorough checking of the data format comes for free as well. For further information about ucesb, see the write-up.


  1. Install ucesb (with FAIRROOT version of ROOT)
  2. Compile your experiment specific unpacker and test it on data
  3. Produce the header file for R3BROOT including the data structure
  4. Extract the parts for each detector and level (unpack / raw)
  5. Install R3BROOT
  6. Write detector specific readers
  7. Write or modify your R3BROOT steering macro
  8. Run the macro

Install ucesb

Checkout the most recent version of ucesb from the git repository at Chalmers:

git clone https://git.chalmers.se/expsubphys/ucesb.git

And also checkout the git repository with experiment unpackers (currently only inside GSI network):

git clone /u/htoernqv/repos/upexps.git
git checkout 202004_s455

Check that

which root

points to your FAIRROOT installation directory!

Compile the empty ucesb unpacker using the same version of ROOT as you used for FAIRROOT.

make -j8 empty/empty

After compilation finished, make sure that the file


exists. This is needed for communication between ucesb and R3BROOT. Set the environment variable UCESB_DIR to the 'unpacker' directory, e.g.

export UCESB_DIR=/u/$USER/path/to/unpacker

Insert this line at the end of your .bashrc (or other shell login script) to make it permanent. R3BROOT will from now on look for ucesb at this location.

Compile your experiment specific unpacker

Also use the same ROOT version here.

cd upexps/experiment_directory
make -j8

Produce the header file

Run ucesb with the struct_writer header generation option

./sNNN --ntuple=<signals>,STRUCT_HH,ext_h101.h

with replacing by RAW or RAW, (replace with the list of detectors you'd like to map). This will produce the header file called 'ext_h101.h'. It contains the structure mapping information for R3BROOT. The data coming from ucesb will adhere to this format.

You can skip parts of the following step, if you do the header writing like this

./sNNN --ntuple=<signals>,id=h101_<detector>,ext_h101_<detector>.h
# Example
./s483 --ntuple=RAW:TOFD,id=h101_tofd,ext_h101_tofd.h

This will already insert the correct detector names for you, and only extract signals related to the specific detector.

Extract the parts for each detector

At this point the following part of the process is still manual: For this example we will use the RAW level data of the LOS detector.

  • Make a copy of ext_h101.h for each detector (e.g. ext_h101_raw_los.h)
  • Rename the EXT_STR_h101.h to EXT_STR_h101_raw_los.h
  • Delete all contents of the structure with don't relate to LOS
  • Delete all contents of the #define EXT_STR_h101_ITEMS_INFO(...) that don't relate to LOS
  • Rename the #define statement to match the structure name.

Install R3BROOT

Installation information can be found on the R3BROOT website

Write detector specific reader classes

Have a look at r3bsource/R3BUnpackReader.[cxx/h]. Your detector specific reader class should almost be a copy of this, mostly replacing 'unpack' with e.g. 'raw_los'. And you will have to make sure that in the Read() function your detector specific data containers are filled with the data from the ucesb structure.

Write or modify your R3BROOT steering macro

An existing steering macro for the s438b experiment can be found in


It shows how the R3BUcesbSource class is used and how Readers are added.

Run the macro

Run this:

root -l path/to/your/macro.C



Either via Mail or in the GSI forum.