Child pages
  • BAM Data Structure

Description of the data structure provided by the Bunch Arrival-time Monitors (BAM). The arrival-time information can be used for post-sorting and jitter correction of experimental data.

Article is intended for users of the FEL facilities.

BAM System

Functionality

The Bunch Arrival-time monitor uses a relative measurement method which compares the timing of each electron bunch against a laser pulse provided by the optical reference system (LbSync); to the same time reference, the pump-probe lasers are phase-locked.

The unit of the BAM data are picoseconds.

The x-axis is given in microseconds, showing the bunch filling pattern as defined in the main timing system.

 Details ...

The actual time t0 = 0ps is an arbitrary offset which is only changed after setting up the system after, e.g., a maintenance time, and has no relevance.

What one usually does, after defining/finding time zero in the experiment, is either observe the relative changes for a single bunch during the course of the measurement run compared to the starting point,

or (in addition) observe the relative deviation across all bunches within the same bunch train.

Those deviations and drifts happen usually only in the order of 50fs to 200fs; depending on the machine setup.

The short-term timing jitter (over several 100 trains) for each individual bunch, i.e. the standard deviation from their mean value, is usually ~ 20fs.

The actual measurement resolution of a BAM can be - currently - as good as 3fs, for each bunch in the full train.

BAM Locations at XFEL

BAM Locations at FLASH


DOOCS/DAQ channel addresses : XFEL.SDIAG/BAM/<location>/

table with location names:

data relevant for...
machine operationSASE1SASE2SASE3
47.I1, 181.B1, 203.B1, 392.B2, 414.B2, 1932M.TL(414.B2, 1932M.TL,) 1932S.TL(414.B2, 1932M.TL,) 1932S.TL(414.B2, 1932M.TL,) 1932S.TL

DOOCS/DAQ channel adresses: FLASH.SDIAG/BAM/<location>/

table with location names:

data relevant for...
machine operationFLASH1FLASH2FFwd (experimental)
1UBC2, 3DBC2,4DBC31SFELC8FL2XTDS7FLFMAFF

Description of Data Sources

The array lengths and fill patterns depend on which source one is choosing when reading the BAM data.


The original DOOCS property of the bunch pattern table has an array length of 7222 entries, and is filled in a 9MHz pattern.

The original DOOCS property of the BAM data has an array length of 7222 entries, and is filled in a 9MHz pattern.


This is the array one will get when pulling the DOOCS property (e.g.) ‘XFEL.SDIAG/BAM/1932M.TL/LOW_CHARGE_ARRIVAL_TIME’ directly from the BAM front-end CPU via RPC.

The same data is also published in a ZMQ channel with according name.

 Details ...

However, to reduce the amount of data being stored in the main DAQ, the DAQ-senders (not only from BAM but also from other bunch diagnostics) are configured such, that only every 2nd entry is sent to the XFEL linac DAQ (and only every 9th entry is sent to the FLASH linac DAQ).

I.e., the BAM DAQ channel ‘XFEL.SDIAG/BAM.DAQ/1932M.TL.LOW_CHARGE_ARRIVAL_TIME’ has an array length of only 3611 entries.

I.e., this data array is effectively filled in a 4.5MHz pattern.


BAM-data array lengths vs. bunch pattern :

Actual Repetition rate

DOOCS

XFEL-DAQ

FLASH-DAQ

4.5MHz

Every 2nd slot is filled

Every slot is filled

-

2.2MHz

Every 4th slot is filled

Every 2nd slot is filled

-

1.1MHz

Every 8th slot is filled

Every 4th slot is filled

-
1.0MHzEvery 9th slot is filled-Every slot is filled
500kHzEvery 18th slot is filled-Every 2nd slot is filled
............


When extracting data from the DAQ, it is provided in hdf5 format. Contact V.Rybnikov (MCS) for support.

The data files are stored (on request) on a local disk of one of the DAQ computers. The data directory of that computer is nfs mounted on computers xfeluser1/2 resp. flashuser1/2.

Read Bunch Data

You need the information from the bunch pattern table, which indices the user bunches had.

  1.  Find the list of indexes from the bunch pattern [filled in 9MHz rate]
  2.  The BAM DAQ-data spectrum starts at first buch time = 800 usec, and is filled with 4.5MHz rate (Sampling increment= 0.2215385)
  3.  If user bunch start index is IDX then the data index in the BAM spectrum is  = 800 + IDX/2.

BAM DAQ Channel Names

Usually only of interest for users are following channels:

propertydata type
LOW_CHARGE_ARRIVAL_TIMED_spectrum, original length 7222 entries
DELTAT_SIGND_floatarray, 3 entries (Flattop1,Flattop2, ~)
BAM_STATUS.1D_int (Flattop1)
BAM_STATUS.2D_int (Flattop2)
BAM_ERRORD_int
Q
 Expand full, detailed list ...

Spectra

LOW_CHARGE_ARRIVAL_TIME (D_spectrum, full length = 7222 entries in 9MHz pattern)
Calibrated arrival time data from the "low-charge channel":
- calibrated arrival time for all bunches and all sub-macropulses
- x-axis: time in microseconds
- y-axis: picoseconds
HIGH_CHARGE_ARRIVAL_TIME (D_spectrum, full length = 7222 entries in 9MHz pattern)
Calibrated arrival time data from the "high-charge channel":
- calibrated arrival time data for all bunches and all sub-macropulses
- x-axis: time in microseconds
- y-axis: picoseconds
LOW_CHARGE_ARRIVAL_TIME_RAW_9MHz_PATTERN (D_spectrum, full length =7222 entries in 9MHz pattern)
- non-calibrated arrival time data from the "low-charge channel":
- modulation data for all bunches (9MHz pattern)
- x-axis: time in microseconds
- y-axis: (rel.units)
HIGH_CHARGE_ARRIVAL_TIME_RAW_9MHz_PATTERN (D_spectrum, full length =7222 entries in 9MHz pattern)
- non-calibrated arrival time data from the "high-charge channel":
- modulation data for all bunches (9MHz pattern)
- x-axis: time in microseconds
- y-axis: (rel.units)

Float Values

ARRIVAL_TIME_OFFSET (D_float)
- general arrival time offset value :
- unit : femtoseconds
LOW_CHARGE.ACCURACY (D_float)
- measurement accuracy of the "low-charge channel":
- statistical error of arrival time measurement
- units : relative
HIGH_CHARGE.ACCURACY (D_float)
- measurement accuracy of the "high-charge channel":
- statistical error of arrival time measurement
- units : relative
DELTAT_SIGN (D_floatarray, 3 entries)
- defines the arrival time unit and direction of time axis:
- factor on y-axis of calibrated arrival time data
  0.001 = picoseconds,
  1 = femtoseconds

Integer Values

For converting to binary word with 12bits to display status bits/logic plot.
BAM_STATUS.1 (D_int)
- Submacropulse 1 (RF Flattop 1) general status of the BAM Channel :
- Description
  1. bit 0 (value:   1) = data is valid,
  2. bit 1 (value:   2) = at least 1 bunch is requested/allowed from main timing,,
  3. bit 2 (value:   4) = calibration is on,
  4. bit 3 (value:   8) = internal feedback is on,
  5. bit 4 (value: 16) = tuning mode is on
BAM_STATUS.2 (D_int)
- Submacropulse 2 (RF Flattop 2) general status of the BAM Channel :
- Description
  1. bit 0 (value:   1) = data is valid,
  2. bit 1 (value:   2) = at least 1 bunch is requested/allowed from main timing,,
  3. bit 2 (value:   4) = calibration is on,
  4. bit 3 (value:   8) = internal feedback is on,
  5. bit 4 (value: 16) = tuning mode is on
BAM_STATUS.3 (D_int)
- Submacropulse 3 (RF Flattop 3) general status of the BAM Channel :
- Description
  • bit 0 (value:   1) = data is valid,
  • bit 1 (value:   2) = at least 1 bunch is requested/allowed from main timing,
  • bit 2 (value:   4) = calibration is on,
  • bit 3 (value:   8) = internal feedback is on,
  • bit 4 (value: 16) = tuning mode is on
BAM_ERROR (D_int)
- general error code of the BAM System:
- Description
  1.      (value :    0) = no error
  2. bit   1 (value :    1) = error from front-end,
  3. bit   2 (value :    2) = Link not locked,
  4. bit   3 (value :    4) = MLO not locked,
  5. bit   4 (value :    8) = error from Motor.1 (for Submacropulse 1),
  6. bit   5 (value :   16) = error from Motor.2 (for Submacropulse 2),
  7. bit   6 (value :   32) = error from Motor.3 (for Submacropulse 3),
  8. bit   7 (value :   64) = error from Motor T (for time-delay between "low-charge channel" and "high-charge channel"),
  9. bit   8 (value : 128) = Toroid connection time-out,
  10. bit   9 (value : 256) = Link connection time-out,
  11. bit 10 (value : 512) = MLO connection time-out




Further Pages

HDF5 library & file format 🔗

FS-FLASH USER Home

Info collection for the BAM (FS-FLASH User)


Journal Articles

Evgeny Savelyev, et al,  Jitter-Correction for IR/UV-XUV Pump-Probe Experiments at the FLASH Free-Electron Laser,
New J. Phys. 19, 043009 (2017), https://doi.org/10.1088/1367-2630/aa652d