Beam properties
extra.components.XGM ¤
Interface to an XGM (X-ray Gas Monitor).
Example usage in a Jupyter notebook:
-----------------------------------------------------------
In [1]: |xgm = XGM(run) # This will work with a single XGM |
|xgm |
-----------------------------------------------------------
Out[1]: <XGM for SA1_XTD2_XGM/XGM/DOOCS at 9.3 keV>
-----------------------------------------------------------
In [2]: |# With multiple XGMs, one needs to be chosen explicitly. |
|# Either by explicit device name: |
|xgm = XGM(run, "SPB_XTD9_XGM/XGM/DOOCS") |
| |
|# Or by passing a SourceData object: |
|xgm = XGM(run, run.alias["spb-xgm"]) |
| |
|# Or a KeyData object: |
|xgm = XGM(run, run.alias["spb-xgm"]["data.intensityTD"]) |
| |
|# Or alias name |
|xgm = XGM(run, "spb-xgm") |
| |
|# Or a unique (case-insensitive) substring among XGMs |
|xgm = XGM(run, "spb") |
-----------------------------------------------------------
Out[2]: <XGM for SPB_XTD9_XGM/XGM/DOOCS at 9.3 keV>
Parameters:
Name | Type | Description | Default |
---|---|---|---|
run |
DataCollection
|
A run containing at least one XGM. |
required |
device |
(str, SourceData, KeyData)
|
Specify an XGM to use, necessary if a run contains more than one XGM. This can be any of:
|
None
|
default_sase |
int
|
Only for XGMs with data for multiple SASE's, to specify a default SASE to retrieve data for. This is useful when working with XGMs on SASE 1 or SASE 3 and you're only interested in data for a specific SASE. This setting applies to all the SASE-specific methods of the class, such as XGM.pulse_energy() and XGM.npulses(). If it is not set the class will try to guess the SASE of the instrument the data was recorded at, and it will throw an error if:
Valid values are: 0, 1, and 3.
Passing 0 always selects the main properties of a device,
e.g. |
None
|
control_source
property
¤
The SourceData
object for the control source of the XGM
(e.g. SA2_XTD1_XGM/XGM/DOOCS
).
instrument_source
property
¤
The SourceData
object for the instrument source of the XGM
(e.g. SA2_XTD1_XGM/XGM/DOOCS:output
).
wavelength ¤
The nominal wavelength of the X-rays in nanometers.
This calls KeyData.as_single_value() internally, which means it will throw an exception if the wavelength is not constant.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
with_units |
bool
|
Whether to return a pint.Quantity or a float. |
True
|
Raises:
Type | Description |
---|---|
ValueError
|
Will be thrown if the number of pulses is not constant. |
photon_energy ¤
The nominal photon energy in keV.
This calls KeyData.as_single_value() internally, which means it will throw an exception if the wavelength is not constant.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
with_units |
bool
|
Whether to return a pint.Quantity or a float. |
True
|
doocs_server ¤
The DOOCS server that the Karabo XGM device is connected to.
This information was not stored in older versions of the XGM, so the
method may return None
if the DOOCS server was not found.
Raises:
Type | Description |
---|---|
MultiRunError
|
A |
pulse_energy ¤
Returns the energy per-pulse and per-train in microjoules.
If series=False
(the default) this will return a 2D
DataArray with dimensions of (trainId,
pulseIndex)
. For runs with a varying number of pulses, the data will be
sliced to the maximum number of pulses. e.g. if a run has 100 trains
with only one train containing 10 pulses and all the others 0, the
returned array will have a shape of (100, 10)
.
If series=True
this will return a 1D Series where all
entries with 0 pulses have been dropped, indexed by trainId
and
pulseIndex
.
Note
This uses the data.intensityTD
property of the XGM.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
sase |
int
|
Specify a SASE to retrieve data for. For XGMs from SASE
1 and SASE 3 this can be either |
None
|
series |
bool
|
False
|
slow_train_energy ¤
Return the slow train energy from the XGM in microjoules.
This is an average pulse energy, averaged over all pulses for 10-20s.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
sase |
int
|
Same meaning as in XGM.pulse_energy(). |
None
|
npulses ¤
The nominal number of pulses.
This calls KeyData.as_single_value() internally, which means it will throw an exception if the number of pulses is not constant.
Note that this returns the number of pulses recorded by the XGM, which can be unreliable. Use something like the XrayPulses component to find the real number of pulses from the bunch pattern table.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
sase |
int
|
Same meaning as in XGM.pulse_energy(). |
None
|
Raises:
Type | Description |
---|---|
ValueError
|
Will be thrown if the number of pulses is not constant. |
pulse_counts ¤
Return a 1D DataArray of the number of pulses in each train.
See the docs for XGM.npulses() for information on retrieving the true number of pulses.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
sase |
int
|
Same meaning as in XGM.pulse_energy(). |
None
|
max_npulses ¤
The maximum number of pulses.
See the docs for XGM.npulses() for information on retrieving the true number of pulses.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
sase |
int
|
Same meaning as in XGM.pulse_energy(). |
None
|
is_constant_pulse_count ¤
Return whether or not the number of pulses is constant.
See the docs for XGM.npulses() for information on retrieving the true number of pulses.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
sase |
int
|
Same meaning as in XGM.pulse_energy(). |
None
|
plot ¤
Plot an overview of data from the XGM.
This combines XGM.plot_pulse_energy(), XGM.plot_energy_per_pulse(), and XGM.plot_energy_per_train() in a single figure.
Example plot:
Parameters:
Name | Type | Description | Default |
---|---|---|---|
sase |
int
|
Same meaning as in XGM.pulse_energy(). |
None
|
figsize |
tuple
|
The size of the Figure. |
(9, 7)
|
plot_pulse_energy ¤
Plot a heatmap of the pulse energies.
Example plot:
Parameters:
Name | Type | Description | Default |
---|---|---|---|
sase |
int
|
Same meaning as in XGM.pulse_energy(). |
None
|
ax |
Axes
|
The axis to plot in. This will default to plt if not provided. |
None
|
minimal_title |
bool
|
Whether to include the proposal/run information and XGM device name in the title. |
False
|
plot_energy_per_pulse ¤
Plot the average pulse energy.
Example plot:
Parameters:
Name | Type | Description | Default |
---|---|---|---|
sase |
int
|
Same meaning as in XGM.pulse_energy(). |
None
|
ax |
Axes
|
The axis to plot in. This will default to plt if not provided. |
None
|
minimal_title |
bool
|
Whether to include the proposal/run information and XGM device name in the title. |
False
|
plot_energy_per_train ¤
Plot the average train energy.
Example plot:
Parameters:
Name | Type | Description | Default |
---|---|---|---|
sase |
int
|
Same meaning as in XGM.pulse_energy(). |
None
|
window_trains |
int
|
The number of trains to use when plotting the rolling average. By default this is chosen automatically based on the number of trains in the run. |
None
|
ax |
Axes
|
The axis to plot in. This will default to plt if not provided. |
None
|
minimal_title |
bool
|
Whether to include the proposal/run information and XGM device name in the title. |
False
|