Receivers/GEBMerge/GEBsort

gtReceiver

To take data with the DGS DAQ, you must start a gtReceiverN (N=3..5) program for each of the IOCs that are collecting data. This is usually done from a script which starts all the necessary receivers and controls the run number.

To get the gtReceiverN receivers, do the following

cd to where you want to compile the gtReceiverN programs
git clone https://gitlab.phy.anl.gov/tlauritsen/gtreceiver.git
make -B

That should generate the gtReceiver4 program. gtReciver5 should work just like gtReceiver4; but it buffers the digitizer data and sorts the timestamps before writing the data to disk. Thus, with gtReciver5 you should be able to run in 'copy' mode, avoiding using the IOC CPU to do the TS sorting task. Here is an example of how to run the programs:

      +---- receiver program
      |        +---- IP/name of IOC to receive from
      |        |        +---- data file name
      |        |        |              +---- max size
      |        |        |              |       +---- GEB ID
      |        |        |              |       |
 gtReceiver4 ioc1 data_run_001.gtd 2000000000 14

Here we are asking gtReceiver4/gtReceiver5 to acquire data from ioc1, use a GEB ID of 14 (see http://gretina.lbl.gov/tools-etc/gebheaders for the official list of GEB header IDs) , and write the data in the file data_run_001.gtd. That will not actually be one file as gtReceiver4/gtReceiver5 splits the data stream into a file for each of the digitizers the IOC serves. That makes it (much) easier to merge and time order the DGS data later. 2000000000 specifies the max size of the files, here keeping them under 2GBytes, so they can be read on all machines. When the size of the file reaches this limit, the file is closed and another file is used.

The gtReceiver4/gtReceiver5 program writes data out in the GRETINA GEBheader/Payload form. This means that the GT GEBMerge and GEBSort programs can be used for DGS data as well as GT data. gtReceiver3 writes data witout GEB headers and should not be used anymore.

The only things the receiver does is to

 get the data from the IOC
 extract the timestamp from the data
 extract the lenght of the data
 extract the board ID

After that, the receiver constructs a GEB header that has this form

 struct gebData {
   int type; /* type of data following */
   int length;
   long long timestamp;
 };

Once constructed, the receiver writes this header to disk followed by the data it received from the IOC. Thus, the data is a series of GEB headers and data, also referred to as the headers and payloads. It is important to recognize that the receiver does not otherwise interpret the data! This makes the receiver simple, universal and fast. Interpretating the date is the task of GEBSort which acts on the data after the merging. The data is stored in individual files based in the channel ID. Thus, if four digitizers are serviced by one IOC, four files are opened. This make the merging of the data easier.

These are the fields that the receiver relies on:

 board_id = ((hdr[0] >>= 4) & 0xfff);  bits:4...15

 packet_len = ((hdr[0] >>= 16) & 0x000007ff); bits:16...26

 Geb.timestamp = (unsigned long long int) hdr[1];
 ulli1 = (unsigned long long int) (hdr[2] & 0x0000ffff);
 ulli1 = (ulli1 << 32);
 Geb.timestamp += ulli1;

In the full data from the IOC that also contains the 0xaaaaaaaa, hdr[0|1|2] would be hdr[1|2|3] The board_id is also referred to as the "USER PACKET DATA" field and uniquely identifies the digitizer.

 NOTE: Please use gtReceiver4 for now. 
 gtReceiver5 is reported to a have a problem.

GEBMerge

To get the GEBMerge program,

 git clone https://gitlab.phy.anl.gov/tlauritsen/GEBSort.git

GEBMerge allows you to merge all the files that the instances of the gtReceiver4 created during your run. In addition to merging the data, GEBMerge also orders the merged data based on the timestamps in the GEB header. This merger and time stamp ordering program will work on all kinds of data, as long as the data are in the GT GEB header/Payload format, including data taken with the gtReceiver4 receiver.

You will use the program as

 GEBMerge GEBMerge.chat outfile     file1  file2  file3  file4 .....

where GEBMerge.chat is the file that contains parameters for the merging, such as the buffer size to use. The merged data will be written to outfile and file1 file2 file3 file4 ..... is the list of files to merge.

GEBMerge is part of the GEBSort package. See the link below for how to get the GEBSort package. gtReceiver4 is specific to DGS; but the GEBSort package can handle many other kinds of data as well. Sometimes you will want to use GEBMerge on GRETINA data as well as the program also time orders the data.

GEBSort

To get the GEBSort program,

 git clone https://gitlab.phy.anl.gov/tlauritsen/GEBSort.git

GEBSort is a rather general purpose ROOT sorter, that, in addition to being able to read GRETINA data, also can read DGS data acquired by gtReceiver4. This sorter is documented under the GRETINA wiki pages

 [1]

Running GEBMerge and GEBSort in interactive mode

It is possible to merge data and look at the data on-line. The trick we apply is to not close an input file to GEBMerge or GEBSort right away when no more data is available. Instead, through the instructions

 waitfordata 300

in both the chatfiles of GEBMerge and GEBSort, we instruct the programs to wait 300 seconds, or 5 minutes, before giving up merging or sorting data. Thus, the programs will merge and sort the data as it comes in and you can set GEBSort up to use a map-file to display the data so that you can update/display like we did for GSSort with the analog Gammasphere DAQ. Here is a reminder about how you set up a map-file with GEBSort. First you set up a root session where you will display the data. Keep this root session up.

 rootn.exe
 .L GSUtil.cc++
 sdummyload(200000000)

that will tell you the start map address for the given size of the root map-file, in this case 200000000. Now, specify this map address, in this example: 0x9ef6e000, when you start GEBSort as

 ./GEBSort_nogeb \
    -input disk merged_data.gtd \
    -mapfile c1.map 200000000 0x9ef6e000 \
    -chat GEBSort.chat 

where 200000000 is the size of the map file you want and 0x9ef6e000 is the start map addess reported by sdummyload as describes above. Now you can go back into the display root sessiong above and load the mapfile

 sload("c1.map")

Then you will do the usual:

 update()
 [display]

 update()
 [display]

If the beam goes away for more than 5 minutes you will have to start the GEBMerge and GEBSort programs again (maybe by starting a new run). At the end of a run, you would kill all the receivers (as usual) and then you can

 pkill -9 GEBmerge
 pkill -9 GEBSort

to stop the programs. In principle, you have now merged the data online and don't need to do that later.