Home

Users's Guide

Start with the 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 in time.
lstcalibrateinsert128: calibrates the size of the buffer necessary to read properly an entire file.
lstexporter128: exports the data.
lstplot128: plots the data.

Before programming, you can start using the tools.
Print the boards and their characteristics:

$ lstboardinfo128

Display the header of the 882390.lst file:

$ lstheader128 882390.lst

Display the events:

$ lstreader128 882390.lst | more

As the number of events should be big, using more allows to see them by block.

If the number of events is small, you can export the binary file in a text file:

$ lstexporter128 882390.lst 882390.txt

You can also filter the events if the resulting file is too big. For instance, limit to the crate 0:

$ lstexporter128 882390.lst 882390.txt "[[0]]"

Limit the number of events to 1000 for the crate 0:

$ lstexporter128 882390.lst 882390.txt "[[0]]" 1000

For more information on the filters, simply:

$ lstexporter128

Program your own reader

First of all, you have to open a file.

#include <lstdpp128/lstdpp.h>

// 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	0
C1751_PSD	1
C1724_PHA	2
C1730_PSD	3
C1730_PHA	4
C1740_QDC	5
C1740_QDIV	6
C1725_PHA	7
C1725_PSD	8
GGPICKUP	20
MCC	21
CAMERA	22
GGDMS	23
GGFMCPICKUP	24

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 working on 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