Introduction
XTCAV is a detector that is used to determine the laser-power vs. time of each LCLS shot. Some detailed documentation from Tim Maxwell on this device is Here. Alvaro Sanchez-Gonzalez authored the original psana-python code to do the rather complex analysis of images from the XTCAV camera to determine these quantities. This current version has been updated to run more quickly and to fix some analysis errors.
These scripts use some XTCAV data that was made public so they should be runnable by all users. The scripts can be found in /reg/g/psdm/tutorials/examplePython/xtcav/ in the files xtcavDark.py, xtcavLasingOff.py, xtcavLasingOn.py.
Analysis Setup
Two things must be done before XTCAV analysis will function: a "dark run" must be analyzed to get the pedestal values for cameras, and a "no lasing" run must be analyzed to generate sets of "no lasing" images (the latter is quite a complex process). Note that for demonstration these first two scripts write constants to a "local" calibration directory called "calib". For a real-experiment you won't need these lines because you will have permission to write to your official experiment calibration-constants directory.
Sample of dark run analysis:
# these first two lines for example purposes only, to allow user to write
# calibration information to local directory called "calib"
# should be deleted for real analysis.
import psana
psana.setOption('psana.calib-dir','calib')
from xtcav.DarkBackground import *
DarkBackground(experiment='xpptut15',
run_number='300', # run number within experiment
max_shots=1000, # maximum number of shots to process
validity_range=(300,302)) # range of runs for which this dark run should be used
Sample of "no-lasing" reference generating script:
# these two lines for example purposes only, to allow user to write
# calibration information to local directory called "calib"
# should be deleted for real analysis.
import psana
psana.setOption('psana.calib-dir','calib')
from xtcav.LasingOffReference import *
LasingOffReference(
experiment='xpptut15',
run_number='301',
max_shots=200,
num_bunches=1,
validity_range=(301,)) #only give first run number to have the validity range be open-ended ("end")
This script can be easily run in parallel by submitting a parallel MPI job to the batch system as described here. Once the dark/lasing-off analysis has been completed, users can analyze the lasing-on events using a standard psana-python script similar to the one below.
Example Analysis Script
This script assumes that dark/lasing-off data has been analyzed (see above). Unlike the previous two scripts it reads dark/lasing-off constants from the official calibration-directory. This script can be found in /reg/g/psdm/tutorials/examplePython/xtcav/xtcavLasingOn.py:
from psana import *
import matplotlib.pyplot as plt
from xtcav.LasingOnCharacterization import *
experiment = 'xpptut15'
run = '302'
mode = 'smd'
ds = psana.DataSource("exp=%s:run=%s:%s" % (experiment, run, mode))
ngood = 0
XTCAVRetrieval=LasingOnCharacterization()
for evt in ds.events():
if not XTCAVRetrieval.processEvent(evt):
continue # continue to next image if analysis fails for some reason
# time and power are lists, with each entry corresponding to
# a bunch number. The number of bunches is set by the GLOC.nb
# parameter in the lasing-off analysis. In general, one should
# also cut on the "agreement" value, which measures the agreement
# between the first and second moment analysis (larger is better).
time, power = XTCAVRetrieval.xRayPower(method='RMS')
agreement = XTCAVRetrieval.reconstructionAgreement()
ngood += 1
print 'Agreement: %g%% ' % (agreement*100)
plt.plot(time[0],power[0])
plt.xlabel('Time (fs)')
plt.ylabel('Lasing Power (GW)')
plt.title('Agreement %4.2f'%agreement)
plt.show()
if ngood > 1:
break
Notes: The LasingOnCharacerization module uses the detector interface to find the datasource being used. The program will fail if you try to process events without first setting a datasource. If you are analyzing an older experiment, you may find that psana does not support the 'smd' mode. Instead, use the 'idx' mode.
One caveat: this data shows "horns" at the beginning and the end of the bunch which confuse the algorithm (the accelerator often behaves in this manner). Only the middle peak in the plotted spectrum is the relevant lasing peak.
Some tips for lasing-on analysis:
- The second-moment analysis (energy spread method) of the XTCAV image generally provides a better estimate of the true power profile of the XTCAV image. It is recommended that you use method='RMS' when calling xRayPower(), as demonstrated above.
- Ignore shots where the X-ray intensity is low, but cutting on the FEEGasDetector value to select stronger shots
Examining The "Ingredients" of the XTCAV Analysis
This is a utility that can help users understand why XTCAV results look the way they do. Run it like this:
xtcavDisp exp=xpptut15:run=302
It produces plots that look like this:
These plots show the following quantities for both lasing-on shot that is being analyzed and the lasing-off shot that it is being compared to (which is selected as the one having the closest current-profile):
- Current
- Energy computed using the first-moment ("Delta") method
- Energy computed using the second-moment ("Sigma") method
- Power
Close the existing plot window to show the plots for the next event.
XTCAV Analysis Parameters
-num_bunches: Number of bunches: typically 1, but can be 2+ for some LCLS experiments. For analysis of a lasing on run, this must be the same as the number of bunches in the reference lasing off run that you're using.
-maxshots: number of images to process for dark background or lasing off reference generation. In principle the bigger the better, but around 1000 should work fine. If you select a bigger number for dark background generation, then you should get a more representative average of the background noise. If you select a bigger number for lasing off reference generation, you will get more references. This will take longer to process but you'll have a better chance of finding a well matched profile when processing lasing on shots.
-num_groups: The number of groups into which lasing off profiles are clustered. Setting this number to 1 would be Increasing this number will make better references, but they may also make them less accurate, as you would be averaging a larger number of profiles. If you decide to increase this number by a factor, then I would also increase n by the same factor, so in the end the total number of reference is the same. (see also thoughts from Tim Maxwell below).
-islandsplitmethod: (default value: 'scipylabel') Several image processing algorithms have been created to separate bunches that appear on the same image. See here for some algorithm details.
- 'scipyLabel' calls the scipy label function to label contiguous regions. this is fast, but requires a region of no signal (after de-noising) between the regions.
- 'autothreshold' tries to separate the islands by automatically finding thresholds that separate them. this is the recommended mode for multi-bunch operation.
- 'contourLabel' tries to adjust a threshold until two large groups are found, grouping together pixels using an opencv contour method. there are two parameters ('ratio1/ratio2') that are settable for the contour method that determine
-roexpand and roiwaistthres: Call the method 'ProcessedXTCAVImage'. If the image does not look clipped, the parameters are fine.
-snrfilter: this one is really sensitive for two bunches, because it sets a threshold based on the noise to higher as the parameter goes up. This means that it is the factor that can separate the two island in case of two bunches, so for two bunch it needs some tweaking until the two bunches are separated for most of the shots. Bottom line:
- For single bunch: As low as possible while still removing the noise (i.e.) not getting noise current profiles.
- For double bunch: As low as possible while separating the two bunches. Call the 'ProcessedXTCAVImage' method again, and look at the size of axis 0: this will be the number of bunches detected. You can probably write a program to automatize the determination of this parameter, until you get lets say a 95% of two bunch detection.
Thoughts from Tim Maxwell on Number of Groups
For various beam conditions (note that Tim describes number-of-groups, but our settable parameter is "groupsize"=number-of-events/number-of-groups):
- normal sase (not many beam-related fluctuations): take sqrt of number shots and use that many groups (beat down background noise with lots of averaging). Tim suggests perhaps a maximum of 100 groups.
- two-bunch slotted foil (many beam-related of fluctuations): restrict it to 5-10 images per group, make as many groups as possible using typically 30 seconds to a minute of data at 60Hz.
- split undulator, single bunch, head and tail lase in separate sections of the split undulator: Tim expects this to be somewhat more chaotic than SASE, but not as chaotic as slotted-foil, so some number of groups in between.
seeded beam: For any results, I would use the SASE settings. However, note that reconstruction for seeding is a little ambiguous. The beam first seeds, so is partly spoiled before seeding itself in the second stage. Therefore it isn't clear exactly with one lasing off reference which part lased more for the seeded part. It is similar to the case when one bunch is used to make two pulses with the split undulator. However, if seeding amplification was strong and intense, this may be enough.
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.
Overview
Content Tools