Aaron: Created page with "{{DISPLAYTITLE: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..."

2026-10-09T21:04:38Z

Created page with "{{DISPLAYTITLE: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..."

New page

{{DISPLAYTITLE: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:

# '''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'''.
# '''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 [[cctbx.xfel GUI/Trials tab#Run block settings|run block settings]] (<code>spectrum_eV_per_pixel</code>, <code>spectrum_eV_offset</code>, <code>wavelength_offset</code>) 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 <code>energy</code> 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 <code>fee/fee_calib.phil</code> next to the output folder):

<pre>spectrum_eV_per_pixel=...
spectrum_eV_offset=...
ebeam_eV_offset=...
wavelength_offset=...</pre>

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.

Cctbx.xfel GUI/Energy tab - Revision history