Users's Guide

Tools

After compiling and installing the library, a set of executables are available:

lstboardinfo128: lists all the supported boards and information attached to the events.
lstheader128: prints the header of a file.
lstreader128: prints the list of events and their data.
lstcheck128: checks a file.
lstsort128: sorts the events of a file.
lstcalibrateinsert128: calibrates the size of the buffer necessary to read properly an entire file.
lstexporter128: exports the data.
lstplot128: plots the data.

Preliminaries

The User's Guide provides essential information on how to use the library. To access the library API you should include:

#include <lstdpp128/lstdpp.h>

Open a File

First of all, you have to open a file.

// The classes are defined in the namespace lstdpp128.
using namespace lstdpp128;

// Initialize a reader with a buffer of size 1024.
Reader reader(1024);

// Open the file.
bool success = reader.open(fileName);

// Exit in case of error.
if (!success) {
	return EXIT_FAILURE;
}

// Print the list mode context.
cout << listModeContext << endl;

The listModeContext object contains the context of the loaded file. It represents the configuration of the electronic cards. The model is the following:

The context contains a Crateboard
A Crateboard contains some Boards
A Board contains some Channels

The Board structure is:

Members	Type
eventType	uint16_t
crate	uint8_t
nbChannels	uint16_t
boardType	BoardType

The BoardType type has the following values:

Constant	Value
CFD_BOARD_TYPE	0
V1751_BOARD_TYPE	1
V1724_BOARD_TYPE	2
V1730_BOARD_TYPE	3

The Crate structure is:

Members	Type
nbBoards	uint16_t
boards	Board*

The boards pointer is the address of the array containing nbBoards Board objects.

The CrateBoard structure is:

Members	Type
nbCrates	uint16_t
crates	Crate*

The crates pointer is the address of the array containing nbCrates Crate objects.

The global listModeContext object of type ListModeContext has the structure:

Members	Type
version	uint32_t
timeBase	uint32_t
nbEvents	uint32_t
crateBoard	CrateBoard

The version member represents the version of the format of the file. The timeBase is the unit of time of the events. The value 9 means that the time base is 10^-9.

Read and Process the File

There are two methods to read and process a file:

Use a simple reader event by event
Use a more advanced processor configured with an algorithm

An example of a simple reader application is provided by SimpleReader.cpp. A more complex example is given in [Plot.cpp] (https://code.ill.fr/lst/lst-data-process-128/blob/master/src/lstdpp128/apps/gnuplot/Plot.cpp).

A more advanced strategy is to use a concept of algorithms used through arrays of events. The advantage is that it is possible to read a block of events, sort them in time and process them. It can be very interesting for very large files for which the entire sequence of events cannot reside in RAM.

The programmer defines a processor class and can use it by two read strategies (EventArray or EventBlockArray). An example of such processor and algorithm is provided by:

Processor Insert.h Insert.cpp
Main IterativeVectorInsert.cpp

Fortran Code as Callback to the Reading of an Event

It is possible to write Fortran code and access to the library lst-data-process-128 as it is shown in this example:
lst128fortran.tar

GitLab

Home