cctbx.xfel GUI/Energy tab

The Energy tab calibrates the per-shot photon energy at LCLS. It is shown only when the facility is LCLS and the GUI is not in monitoring mode. The tab runs its calculations in the Calib Worker thread, whose light turns yellow while a calibration is running and green when it is idle.

Back to cctbx.xfel GUI.

Background

At LCLS each shot's photon energy can be measured two ways: from the electron beam energy reported by the accelerator (the ebeam), and from the FEE spectrometer, which records the spectrum of every pulse on a one-dimensional detector. The spectrometer gives the better value, but its pixel axis must be calibrated into eV. This tab does that in two steps:

1. FEE calibration: several short runs are collected with the beam energy stepped through a notch of known energy. Fitting the notch position in each run's average spectrum against the known energies gives the spectrometer's eV per pixel and eV offset.
2. Ebeam calibration: with the spectrometer calibrated, its per-shot energies are compared with the ebeam energies over a set of ordinary runs to find the constant ebeam offset (and the equivalent wavelength offset), so that the ebeam value can be corrected on shots where the spectrometer is unusable.

The results are entered into run block settings (spectrum_eV_per_pixel, spectrum_eV_offset, wavelength_offset) so that processing jobs use the calibrated energies.

FEE Energy Scan Description

• Experiment: the LCLS experiment the scan runs belong to. Defaults to the experiment in Settings; change it if the scan was collected under a different experiment.
• Max events: how many shots of each run to average (200 by default). More shots give a cleaner spectrum but take longer.
• Run / Notch Energy (eV) table: one row per calibration run. Click a cell to edit it. Add Row appends a row and Clear All empties the table.
• Run Calibration: checks that each run exists and each energy is a number, then runs the calibration in the background. Two plots fill in when it finishes: the trendline (notch position against energy, with the fitted line) and the spectra (each run's averaged spectrum with its detected notch). Each plot has a matplotlib toolbar for zooming and saving.

Runs for Ebeam Calibration

• The checklist shows every run in the database; Refresh picks up runs that arrived since the tab was opened and Clear unticks everything and clears the plot.
• Tick the runs to compare and press Run Calibration. The FEE calibration must have been run first, and each run must belong to a run block (the detector address is taken from it). Runs that are in no run block are skipped with a message in the terminal.
• The plot overlays the ebeam energies with the calibrated spectrometer energies for the selected runs. The worker writes a small locator file per run to an energy folder next to the output folder.

Calibration Results

The box shows FEE eV per pixel, FEE eV offset and Ebeam offset (in eV, with the equivalent wavelength offset in Å). Save calibration writes them as a PHIL file (default fee/fee_calib.phil next to the output folder):

spectrum_eV_per_pixel=...
spectrum_eV_offset=...
ebeam_eV_offset=...
wavelength_offset=...

The first two go into the spectrum_eV_per_pixel and spectrum_eV_offset fields of a run block and the wavelength offset into its wavelength_offset field. Since changing those fields creates a new run block, do the calibration before starting the main processing where possible, or create a new trial with the calibrated run block afterwards.