11. General purpose waveforms analysis: `waan` module

waan is a general purpose waveforms analysis software. It allows users to define their own waveforms analysis routines, without worrying about the inner workings of the ABCD data acquisition system. The user is responsible to write two libraries in C99, that take a waveform as input and outputs one or more processed event. The user functions can be modified and reloaded at runtime, simplifying the development phase.

11.1. Module structure

Listing 11.1 Diagram of the structure of the waveform analysis module waan.

                                                   +-------------------+
                                                   | +-------------------+
                                                   | | +-------------------+
+----------+                                       | | | user libraries    |
| Waveform | <== In the form of an                 +-| | (may be different |
+----------+     event_waveform object,              +-| for each channel) |
     |           see include/events.h                  +-------------------+
     v                                                           |
+----------------------+    +--------+    +------------------+   |
| user function:       | <- | user   | <- | user function:   | <-+
| timestamp_analysis() |    | config |    | timestamp_init() |   |
+----------------------+    +--------+    +------------------+   |
     |             |                                             |
     v             v                                             |
+----------+   +-------+                                         |
| Waveform |   | Event | <== In the form of an                   |
+----------+   +-------+     event_PSD object,                   |
     |             |         see include/events.h                |
     v             v                                             |
+----------------------+    +--------+    +----------------+     |
| user function:       | <- | user   | <- | user function: | <---+
| energy_analysis()    |    | config |    | energy_init()  |
+----------------------+    +--------+    +----------------+
     |             |
     v             v
+----------+   +-------+
| Waveform |   | Event | <== The results are then forwarded
+----------+   +-------+     to the rest of the DAQ
                             They may be discarded by the
                             user functions, to eliminate
                             unwanted events.

11.2. Analysis functions

Two analysis functions are foreseen in the structure (see Listing 11.1):

timestamp_analysis() that determines the timestamp information of the waveform;
energy_analysis() that determines the energy information of the waveform.

The two analyses were separated in order to simplify code reuse. The user might want to perform both analyses in the energy_analysis() function, in order to optimize the computational time. The functions may be different for each acquisition channel, allowing the coexistence of different detectors on the same digitizer. A waveform may also be discarded by the user functions, in order to eliminate unwanted/noise events.

For some considerations on how the timestamp is calculated see Section 10.

11.3. Configuration

The configuration file is in the JSON format. For each channel the user shall provide the filename of the libraries. The timestamp analysis may be omitted without putting a name on the relative library. The libraries may be modified and reloaded at runtime. A reconfiguration command always implies a reload of the user libraries. Configurations may be sent through the web-interface.

Warning

The library filenames in the configuration shall follow the conventions of the UNIX dynamic linking functions. If the filename contains a slash (/) then the file is searched on the given path, if there is no slash then the library is searched in the standard system library directories. If the user wants to use a local file in the current directory the filename shall start with ./ (e.g. ./libCFD.so).

Each channel configuration may contain a user defined configuration. This information is then passed to the init functions of the user libraries, so the user does not have to hardcode the functions parameters.

11.4. Example configuration

Listing 11.2 Example configuration of the waan module. This configuration is used in the example startup that replays example data.

{
    "module": "waan",
    "forward_waveforms": true,
    "enable_additional": true,
    "discard_messages": false,
    "channels": [
        {
            "id": 1,
            "name": "LaBr",
            "enabled": true,
            "user_libraries": {
                "timestamp": "libCFD.so",
                "energy": "libPSD.so"
            },
            "user_config": {
                "baseline_samples": 64,
                "smooth_samples": 16,
                "fraction": 0.75,
                "delay": 5,
                "zero_crossing_samples": 2,
                "fractional_bits": 10,
                "disable_shift": true,
                "pregate": 40,
                "short_gate": 30,
                "long_gate": 90,
                "pulse_polarity": "negative",
                "integrals_scaling": 2
            }
        },
        {
            "id": [ 6, 7 ],
            "name": "CeBr",
            "enabled": true,
            "user_libraries": {
                "timestamp": "libCFD.so",
                "energy": "libPSD.so"
            },
            "user_config": {
                "baseline_samples": 64,
                "smooth_samples": 16,
                "fraction": 0.75,
                "delay": 20,
                "zero_crossing_samples": 2,
                "fractional_bits": 10,
                "disable_shift": true,
                "pregate": 40,
                "short_gate": 30,
                "long_gate": 90,
                "pulse_polarity": "negative",
                "integrals_scaling": 2
            }
        }
    ]
}

Listing 11.2 shows a configuration example. More examples can be found in the /usr/share/abcd/waan/ directory. A detailed list of configurations follows:

forward_waveforms: Bool value that enables the forwarding of the processed waveforms. A user may disable the forwarding in order to avoid the data saver to save them in the raw files, thus reducing their dimensions.
enable_additional: Bool value that enables the forwarding of the additional waveforms. These waveforms are calculated by the user libraries for debugging purposes and in general do not need to be stored. In case a user wants to store waveforms, the additional waveforms take up a lot of space and are preferably disabled.
discard_messages: Bool value that enables the message dropping. In case of experiments with very high data throughput the operating system kernel may decide to drop messages to preserve the memory usage. This setting should disable that, but it depends on the operating system and it might not actually work.
channels: Array value of objects. This array contains the settings of the single channels. Each channel object has the settings:
- id: Integer value that indicates the channel to which these settings apply. It may be substituted with an array of integer values, indicating that these settings are to be replicated to all these channels.
- name: Just a mnemonic string for the user. The program actually ignores this setting.
- enabled: Bool value to quickly enable or disable this channel settings.
- user_libraries: An object containing the paths of the user libraries. The timestamp library is optional, if not set then waan will use the digitizer timestamp for the waveform. The energy library is mandatory. If waan is unable to load the energy library then the channels in the id settings will be disabled.
- user_config: An object that is provided to the user libraries by waan. Its content depend totally on the user libraries. Refer to their documentation.

11.5. Libraries compilation

The user libraries shall be implemented with a C99 interface, so no C++. The /usr/share/abcd/waan_libraries/ directory contains some documented examples. The user may compile the custom library with the provided Makefile. The user should make a new .c file in the waan_libraries/src/ directory:

user-tutorial@abcd-tutorial:~$ mkdir abcd_tutorial
user-tutorial@abcd-tutorial:~$ cd abcd_tutorial
user-tutorial@abcd-tutorial:~/abcd_tutorial$ cp -r /usr/share/abcd/waan_libraries/ .
user-tutorial@abcd-tutorial:~/abcd_tutorial$ cd waan_libraries
user-tutorial@abcd-tutorial:~/abcd_tutorial/waan_libraries$ nano src/libuser.c
user-tutorial@abcd-tutorial:~/abcd_tutorial/waan_libraries$ make
...
...

The new library will be src/libuser.so. To load the library in waan use the full path in the configuration, such as: /home/user-tutorial/abcd_tutorial/waan_libraries/src/libuser.so

11.6. Example libraries

Some example libraries are provided in the /usr/share/abcd/waan_libraries/ directory. They are extensively commented and documented in the source code. These example libraries are provided:

libSimplePSD.c: Calculates the energy and Pulse Shape information of a short pulse, by applying the double integration method. This is the simplest of the libraries, that can be a starting point for new users.
libLE.c: Calculates the timing information of a pulse by applying a Leading Edge Discriminator algorithm.
libCFD.c: Calculates the timing information of a pulse by applying a Constant Fraction Discriminator algorithm.
libRT.c: Calculates the timing information of a pulse by looking at a threshold crossing point, where the threshold is relative to the pulse maximum. This shows an example of an algorithm that can generate multiple processed events.
libPSD.c: Calculates the energy and Pulse Shape information of a short pulse, by applying the double integration method.
libStpAvg.c: Calculates the energy information of a exponentially decaying pulse, by compensating the decay and determining its height with simple averages.
libCRRC4.c: Calculates the energy information of a exponentially decaying pulse, by compensating the decay and then applying a recursive CR-RC^4 filter.
libRC4.c: Calculates the energy information of a short pulse, by applying a recursive RC^4 filter and determining the maximum.

11.7. User interface

The tutorial has an extensive description of the web-based user interface (see Section 3.2.4).

11.8. Replay of data files

waan is now able to directly read raw files (.adr) and process their waveforms. This allows the fastest reanalysis of waveforms stored in data files, compared to the approach using replay_raw. The data input option (-A) allows the user to select a data source: either a ZeroMQ socket (with a tcp:// prefix) or a file address (with a file:// prefix). For a file address the data source should have the form file://<path_to_file> then data will be read from the raw file. The path may be absolute (e.g. file:///home/user/data/data.adr) or relative (e.g. file://../data/data.adr, mind the number of /). The file may not be compressed. When the file is finished, waan will quit and will produce a message in its status socket.

11. General purpose waveforms analysis: waan module