GAMMASPHERE event data format

The data events are written to tape as:

first all clean germanium events
then (optionally) dirty germanium events
then (optionally) clean bgo events
if there is external data, then follows
- ```
    0xff00
    nn        --> number of external FERA data words
```
- then FERA data/header words (if any)
finally, you should see 0xffff, the end-of-event marker

For 'clean' and 'dirty' germanium words:

The actual data structure on the GS tapes depends on what mode-flags (bits) are set in the ModeFlags field.

The following three words are ALWAYS present:

1 hpid       bgo hit pattern    (0xfe00) |1111|1110|0000|0000| [1]
             and ge hit bit     (0x0100) |0000|0001|0000|0000|
             and id register    (0x00ff) |0000|0000|1111|1111| 
2 ge_high    14 bit high res ge (0x3fff) |0011|1111|1111|1111|
             and over-range bit (0x4000) |0100|0000|0000|0000|
             and Pileup bit     (0x8000) |1000|0000|0000|0000|
3 ge_side    12 bit side ch ge  (0x0fff) |0000|1111|1111|1111| [2]

The appropriate mask to extract the information is shown both in hex and binary formats.

The rest of the events depend on what EFF write out options are on:

If the "writeget" [4] (germanium time) or "writegef" [5] (trap + lowres signals) are set

4 ge_time 12/13 bit[5] ge time  (0x1fff) |0001|1111|1111|1111|

If "writegef" [5] (trap + lowres signals) is set:

5 ge_trap    12 bit trap corr   (0x0fff) |0000|1111|1111|1111|
6 ge_low     12 bit low res ge  (0x0fff) |0000|1111|1111|1111|

If "writebgo" [6] (clean bgo) is set:

7 bgo_time   12 bit bgo time    (0x0fff) |0000|1111|1111|1111| [3]
8 bgo_low    12 bit bgo energy  (0x0fff) |0000|1111|1111|1111| [3]

(The dirty germaniums are only written out if the writeallge[7] bit is set)

For 'clean' BGO data events:

If the writeallbgo[8] bit is set then the so-called 'clean' BGO data would follow the clean ge data and dirty ge data data. The format of the 'clean' BGO events are:

1 hpid       bgo hit pattern    (0xfe00) |1111|1110|0000|0000|
             and ge hit bit     (0x0100) |0000|0001|0000|0000|
             and id register    (0x00ff) |0000|0000|1111|1111| 
2 ge_high    14 bit high res ge (0x3fff) |0011|1111|1111|1111| [4]
             and over-range bit (0x4000) |0100|0000|0000|0000| 
             and Pileup bit     (0x8000) |1000|0000|0000|0000| 
3 ge_side    12 bit side ch ge  (0x0fff) |0000|1111|1111|1111| [4]
4 ge_time 12/13 bit[5] ge time  (0x1fff) |0001|1111|1111|1111| [4]
5 ge_trap    12 bit trap corr   (0x0fff) |0000|1111|1111|1111| [4]
6 ge_low     12 bit low res ge  (0x0fff) |0000|1111|1111|1111| [4]
7 bgo_time   12 bit bgo time    (0x0fff) |0000|1111|1111|1111| 
8 bgo_low    12 bit bgo energy  (0x0fff) |0000|1111|1111|1111|

no matter what "writeget"[4], "writegef"[5] or "writebgo" [6] are set to (but these bits still control how clean and dirty ge data are written out).
--------------

[1] if any of the upper 7 bits are set in a clean event it means that the event was honeycomb Compton-suppressed by the EFF processors.

NEW: Above statement is not totally true! While looking throughh the EFF code in April 2005, it was discovered that events where there was a 'suppression', but either the germanium time or BGO detector time was outside the prompt time limits, are marked in the bgo hit pattern as well. Thus, to do the proper honeycomb suppression one should only honeycomb suppress IF the BGO bit pattern shows a number from 1 to 110 (the suppressing detector number). If you see other numbers (like 125 and 126) one should probably NOT honeycomb suppress!

If you want to use honeycomb suppression you should be very careful about setting proper prompt time windows both for the germanium and BGO detectors. Don't forget to do the same for the calibration runs afterwards when the time might come out differently.

[2] the side channel is attached to the upstream side of the split detectors! (except detector 57 which has it's side channel attached to the downstream side).

[3] not written out for clean germanium detectors if RecordVer=1, see update note below. They are written out for dirty germaniums.

[4] not written out if RecordVer=1, see update note below

[5] If the RF time subtraction is on, another 12 bit word (the TAC2 word from the data header) is subtracted from the original time and 4096 is added. Hence, on the tape this data word will appear to have 13 bits.

--------------
WARNING: on 98/4/1 it was discovered that there was a prompt time condition of the dirty germanium and clean bgo counters in the event header. Thus, as opposed to what the documentation says, you cannot use these counters to figure out the what events are what (dirty ge and clean bgo's that is) on your data tape. This is only a problem if you do write out dirty germanium data and clean BGO data though. If you run writing out only clean GS germanium data, there is no problem. This change was made apparently made on 4/14/97 -- long time before the array was moved to ANL. We are still pondering what to do about this problem.

98/4/10: The fix to the above problem was suggested by Mike: If we write dirty germaniums out then we change the dirty germanium counter in the header to the actual number of dirty germaniums without the time gate. We do the same for the clean BGO events. This way there will be no problems reading the data. The only thing is that if you do write dirty germaniums or clean BGO data out - you must yourself set the time gates (you now have the data to do that) in order to find the time gated K. This is in line with the write out of the clean germanium events where you must also yourself apply a time gate to get the prompt K. This change in the eff code took place just before the GSFMA14 run. The problem with the junk after the buffer header was fixed as well. There should now be one more valid event per buffer since the header for the first event now is written to tape correctly.

update history:

05/4/27: warned that one has to be careful with the honenycomb suppression. Some events are marked as honeycomb suppressed, but really should not have been. See the [1] note.
99/8/6: Data format changed slightly to avoid writing out zeroes when ALL germaniums and/or ALL BGO detecotors are written out. The change is as follows:
- when BGO detecors are written out, then the BGO energy and time signals are suppressed for the clean germaniums (since they are per definition zero).
- For clean BGO detectors the germanium signals: hires,side-energy, ge-time,ge_trap and ge-low signals are suppressed (since they are per definition zero).
These changes were suggested by Carl Svensson and adopted as permanent changes to the GS data structure. Records written out with the new more efficient data format have RecordVer=1 in the data record header. Older data has RecordVer=0. We may still run the old format from time to time on users request.
98/8/18: tiny bug in honeycomb suppression documentation was fixed.
98/4/10: header counters for dirty germaniums and clean BGO events changed to fix an inconsistency in the data format. The problem with the junk after the header was fixed as well.
98/4/6: warning about the dirty ge counters and clean BGO counters in the header not matching the data in the event.
98/3/5: Tried to fully document the writeallge and writeallbgo modeflag bits do to the data format. It's not too transparent - perhaps the EFF code should be changed a bit when it comes to how data is written out when the writeallbgo bit is on.
96/1/26: The upper bits in the Ge hires now contains bits that indicate pile-up and over-range conditions. Gs39 was the last run before this change.
Please note: in future releases of the EFF (event filter formatter) code, pile-up events will no longer be written out (they are of no use). Likewise, over-range events may not be written to the tape stream either.
96/11/8: The upper 8 bits of the hpid for CLEAN events may now signify a honey-comb suppression.
95/3/21: The ge_side write-out changed. It is now always written out in the 3'rd word. Gs9 was the last run before this change.

If you find errors in this GAMMASPHERE documentation; please send E-mail to Torben.