New XTCAV Documentation

Introduction

The XTCAV (X-band Transverse deflecting mode CAVity) is a detector that is used to determine the x-ray power vs. time of each LCLS shot. It can also be used to give information about the relative energies and arrival times of x-ray pulses that are closely spaced in time (fs delays). Unfortunately, some data analysis is necessary to extract this "power profile" from the raw detector signal. This documentation will go through how to do this.

For most experiments, the analysis should be basically turn-key using the code we provide at LCLS. The "Quickstart" section should be enough if you just want to do that as fast as possible. Many experiments that rely heavily on the XTCAV, however, operate in unique electron-beam modes (multibunch, etc) that require more manual fine-tuning of the analysis. To support those cases, we go through a little of the theory behind the XTCAV & analysis routines used to extract the information of interest.

Some knowledge of the physical setup is necessary to understand any data processing results. The XTCAV works by sending the electron beam at the end of the LCLS (after the undulators, so after x-rays have been generated) through a transverse accelerator that "kicks" the electrons, causing the front (early) part of the beam to head one direction, and the back (late) to head the other way. Then, the beam is sent through a magnetic field, which bends it; electrons with high kinetic energy bend a little less than those with low KE. Here is a little schematic:

In this way, the electrons get sorted by both time and energy. The beam hits a fluorescent screen that is imaged by a camera – this image is the raw data we process. A typical XTCAV images looks like this, with "time" on the x-axis and "energy" on the y-axis:

You may notice there are vertical streaks in this image. Those streaks reflect the energy some electrons lost when they generated x-rays in the XFEL undulator! If we compare this image to a comparable image that did not generate x-rays ("lasing off" run, more on that later) then we can "reconstruct" the x-ray power as a function of time.

Contents

Quickstart

All XTCAV analysis is a three step process involving "dark", "lasing off", and "lasing on" runs. The first two are references; the last is how we commonly refer to runs that contain data of interest. Simple scripts are provided as part of the psana python environment for processing each.

Dark Runs

Dark runs are used to simply make pedestals for the XTCAV camera and other diagnostics. These runs without any electrons going through the accelerator. We take the average of a series of dark run images to get the general pixel values of the camera background. We can then subtract this "average image" from the lasing on and off runs to get a closer approximation of the actual energy of the electron bunches.

LCLS provides an "xtcavDark" script that automatically populates the experiment calib dir with dark images that are picked up in subsequent analysis. Just provide an experiment and run number, and optionally the maximum number of shots to process:

xtcavDark amox23616 104 --max_shots 400

Output

dark background reference
  Experiment: amox23616
  Run: 104
  Valid shots to process: 400
100.0 % done, 400 / 400
Maximum number of images processed

Lasing Off Runs

Lasing off runs provide a reference of what the electron beam would have looked like if it did not lose any energy to generate x-rays. To provide this reference, a "lasing off" run is generated that has electons but no x-rays. These electron bunches are captured on the XTCAV camera. The standard analysis clusters together these lasing off images into an (automatically or manually chosen) number of groups. Each cluster of lasing off images is averaged to reduce noise, and then compared to "lasing on" bunches (next step, below). Clustering and subsequent matching to lasing on bunches is done by comparing the electron current as a function of time (projection of the XTCAV image onto the x-axis, the time axis), which is physically expected to be invariant, whether lasing occurred or not.

A script to generate lasing off references is provided with an interface very similar to the one for dark runs. It has quite a few options and should handle nearly all use cases.

xtcavLasingOff amox23616 131 --max_shots 200

Output

Lasing off reference
	 Experiment: amox23616
	 Runs: 131
	 Number of bunches: 1
	 Valid shots to process: 200
	 Dark reference run: None
100.0 % done, 200 / 200
Averaging lasing off profiles into  12  groups.

Lasing On Runs

Runs with data of interest are commonly referred to as "lasing on". For each shot, we choose an aggregated lasing off profile with the most similar electron current. That reference is used to compute the energy that was lost to x-rays. There are two methods by which one can perform that calculation (physical details below): one can either compare the "energy loss" directly – ie subtract the mean electron energy in the lasing off run from the lasing on run -- or look at the increased energy spread in lasing on run vs. lasing off. Both are motivated by FEL theory.

We provide a third simple script that can be used to test these methods:

xtcavLasingOn amox23616 137 --max_shots 5

Output

Using file 104-end.data for dark reference
Using file 131-end.data for lasing off reference
Agreement: 91.4276%; Maximum power: 6.64857; GW Pulse Delay: 18.512 
Agreement: 91.1052%; Maximum power: 5.82139; GW Pulse Delay: 20.6758 
Agreement: 93.136%; Maximum power: 4.88641; GW Pulse Delay: 18.0389 
Agreement: 94.1173%; Maximum power: 6.76523; GW Pulse Delay: 16.2321 
Agreement: 92.9344%; Maximum power: 7.14828; GW Pulse Delay: 11.2065 

For real analysis, however, you likely want to incorporate some python code into whatever analysis masterpiece you are composing.

from xtcav2.LasingOnCharacterization import LasingOnCharacterization
XTCAVRetrieval = LasingOnCharacterization() 


for evt in ds.events():
	XTCAVRetrieval.processEvent(evt)
	t, power = XTCAVRetrieval.xRayPower()

Theory

Differences from Previous XTCAV code

• Changes to the user interface:
  • All parameters should be set during the initialization of `DarkBackgroundReference`, `LasingOffReference`, and `LasingOnCharacterization`.
  • There is no longer a `.Generate()` call. A reference will be created upon initialization of the `DarkBackgroundReference` and `LasingOffReference` classes. The reference will be saved to the psana data directory (default location unless the `calibration_path` parameter is set). If you would like to access the generated reference profiles, you can either load them from the saved file or access the member variable `averaged_profiles` within the `LasingOffReference` class.
  • Some parameters, such as roi_waist_threshold, have been deprecated. The current code automatically chooses this value for you based on the `snr_filter` (see documentation above). Other parameter names have changed so that naming convention is consistent across the entire xtcav package (again, see documentation above). 
• Changes to analysis:
  • Improved profile clustering algorithm
  • Image is no longer median filtered before analysis
  • Power profile for lasing off image is not averaged between RMS and COM methods
• Other changes include: improved code readability, integration with psana detector interface, and speed up in processing time.

Detector Resolution

(From Tim Maxwell)

Time resolution is around 1.1 fs RMS for soft x-rays, 2.5 fs fwhm (in quadrature, of course). So actually pulse length is probably 4.3 - 9.7 fs FWHM.

This also doesn't include the "slippage resolution." That is, if they're using the full undulator, then by the end the x-rays can have slipped out of the electron slice by ~3 fs for soft x-rays. Obviously not a small number if trying to make 5 fs pulses. They've been advised to not use the full undulator when shorter pulses are more important than number of photons.