\(\renewcommand\AA{\unicode{x212B}}\)
PDCalibration v1¶
Summary¶
This algorithm determines the diffractometer constants that convert diffraction spectra from timeofflight (TOF) to dspacing. The results are output to a calibration table.
Properties¶
Name 
Direction 
Type 
Default 
Description 

InputWorkspace 
Input 
Mandatory 
Input workspace containing spectra as a function of TOF measured on a standard sample. 

StartWorkspaceIndex 
Input 
number 
0 
Starting workspace index for fit 
StopWorkspaceIndex 
Input 
number 
Optional 
Last workspace index for fit is the smaller of this value and the workspace index of last spectrum. 
TofBinning 
Input 
dbl list 
Mandatory 
Min, Step, and Max of TOF bins. Logarithmic binning is used if Step is negative. Chosen binning should ensure sufficient datapoints across the peaks to be fitted, considering the number of parameters required by PeakFunction and BackgroundType. 
PreviousCalibrationFile 
Input 
string 
An existent file to be loaded into a calibration table, which is used for converting PeakPositions from dspacing to TOF. Allowed extensions: [‘.h5’, ‘.cal’] 

PreviousCalibrationTable 
Input 
An existent calibration table used for converting PeakPositions from dspacing to TOF. This property has precedence over PreviousCalibrationFile. 

PeakFunction 
Input 
string 
Gaussian 
Function to fit input peaks. Allowed values: [‘BackToBackExponential’, ‘Gaussian’, ‘Lorentzian’, ‘PseudoVoigt’, ‘IkedaCarpenterPV’] 
BackgroundType 
Input 
string 
Linear 
Function to fit input peaks background. Allowed values: [‘Flat’, ‘Linear’, ‘Quadratic’] 
PeakPositions 
Input 
dbl list 
Mandatory 
Commadelimited positions (dspacing) of reference peaks. Care should be taken to avoid using peaks whose predicted positions are too close considering their peak windows. 
PeakWindow 
Input 
dbl list 
0.1 
Width of the window (dspacing) over which to fit a peak. If a single value is supplied, it will be used as half the window width for all peaks. Otherwise, the expected input is a commadelimited list of 2*N window boundaries, where N is the number of values in PeakPositions. The order of the window boundaries should match the order in PeakPositions. 
PeakWidthPercent 
Input 
number 
Optional 
Used for estimating peak width (an initial parameter for peak fitting) by multiplying peak’s value in PeakPositions by this factor. 
MinimumPeakHeight 
Input 
number 
2 
Used for validating peaks before and after fitting. If a peak’s observed/estimated or fitted height is under this value, the peak will be marked as an error. 
MaxChiSq 
Input 
number 
100 
Used for validating peaks after fitting. If the chisquared value is higher than this value, the peak will be excluded from calibration. The recommended value is between 2 and 10. 
ConstrainPeakPositions 
Input 
boolean 
False 
If true, a peak center being fit will be constrained by the estimated peak position +/ 0.5 * “estimated peak width”, where the estimated peak position is the highest Yvalue position in the window, and the estimated peak width is FWHM calculated over the window data. 
HighBackground 
Input 
boolean 
False 
Flag whether the input data has high background compared to peaks’ heights. This option is recommended for data with peaktobackground ratios under ~5. 
MinimumSignalToNoiseRatio 
Input 
number 
0 
Used for validating peaks before fitting. If the signaltonoise ratio is under this value, the peak will be excluded from fitting and calibration. This check does not apply to peaks for which the noise cannot be estimated. The minimum recommended value is 12. 
CalibrationParameters 
Input 
string 
DIFC 
Select which diffractometer constants (GSAS convention) to determine. Allowed values: [‘DIFC’, ‘DIFC+TZERO’, ‘DIFC+TZERO+DIFA’] 
TZEROrange 
Input 
dbl list 
Range for allowable calibrated TZERO value. Default: no restriction. 

DIFArange 
Input 
dbl list 
Range for allowable calibrated DIFA value. Default: no restriction. 

UseChiSq 
Input 
boolean 
False 
Defines the weighting scheme used in the leastsquares fit of the extracted peak centers that determines the diffractometer constants. If true, the peak weight will be the inverse square of the error on the fitted peak center. If false, the peak weight will be the square of the fitted peak height. 
OutputCalibrationTable 
Output 
Mandatory 
Output table workspace containing the calibration. 

MaskWorkspace 
Output 
MaskWorkspace 
_empty_ 
Mask workspace (optional input / output workspace): when specified, if the workspace already exists, any incoming masked detectors will be combined with any additional outgoing masked detectors detected by the algorithm 
DiagnosticWorkspaces 
Output 
WorkspaceGroup 
Mandatory 
Auxiliary workspaces containing extended information on the calibration results. 
MinimumPeakTotalCount 
Input 
number 
Optional 
Used for validating peaks before fitting. If the total peak window Yvalue count is under this value, the peak will be excluded from fitting and calibration. 
Description¶
This algorithm takes an InputWorkspace
containing powder diffraction spectra from a standard sample with xunits of timeofflight (TOF).
These spectra are fitted to extract the Bragg peak positions. The extracted peak positions are then used to
determine the diffractometer constants that convert diffraction spectra from TOF to dspacing. These constants are described in detail
in AlignDetectors v1. The number of the constants being determined (1,2,or 3) is controlled by CalibrationParameters
.
The results are output to a diffraction calibration workspace.
Unlike other calibration algorithms (see TimeofFlight Powder Diffraction Calibration),
peak fitting in PDCalibration is done in TOF, not dspacing. Correspondingly, the input PeakPositions
and PeakWindow
values are converted
from dspacing to TOF. The conversion is based on either the old calibration (see PreviousCalibrationFile
and PreviousCalibrationTable
) or,
if not provided, on the instrument geometry contained in the InputWorkspace
.
The peak fitting properties are explained in more detail in FitPeaks v1. This is used to perform a leastsquares fitting of peaks using as much information as is provided as possible. Each input spectrum is calibrated separately following the same basic steps:
The
PeakPositions
are used to determine fit windows in combination withPeakWindow
. The windows are half the distance between the provided peak positions, with a maximum size ofPeakWindow
.The positions and windows are converted to TOF for the spectrum using either the previous calibration information or the instrument geometry.
For each peak, the background is estimated from the first and last ten points in the fit window.
For each peak, the nominal center is selected by locating the highest point near the expected position. The height is used as the initial guess as well.
For each peak, the width is estimated by multiplying the peak center position with
PeakWidthPercent
or by calculating FWHM of the data in the window.For each peak, parameters (such as center, height, and width) are fitted with leastsquares.
All of the fitted peak centers, weighted according to
UseChiSq
, are used in a separate leastsquares procedure to determine the diffractometer constants.
If more than one constant is requested, the result that has the lowest reduced chisquared value is returned. This favors using less parameters.
When not specified using the MaskWorkspace
parameter, the default name for the mask workspace will be the OutputCalibrationTable
parameter + _mask
. If the mask workspace already exists, its masked values will be combined with those from any uncalibrated pixels detected during the algorithm’s execution.
The resulting calibration table can be saved with
SaveDiffCal v1, loaded with LoadDiffCal v1 and
applied to a workspace with AlignDetectors v1. There are also
three workspaces placed in the DiagnosticWorkspace
group. They are:
evaluated fit functions (
_fitted
) which is theOutputPeakParametersWorkspace
from FitPeaksraw peak fit values (
_fitparam
) which is theFittedPeaksWorkspace
from FitPeaksuncertainties in raw fit values (
_fiterror
) which is theOutputParameterFitErrorsWorkspace
from FitPeaks whenUseChisSq=True
is setpeak fitted positions in dspace (
_dspacing
) derived from the effective peak parameterspeak widths (
_width
) derived from the effective peak parameterspeak heights (
_height
) derived from the effective peak parametersinstrument resolution (deltad/d
_resolution
) derived from the average of effective width/height of each peak. This is only correct for Gaussian and Lorentzian peak shapes
Since multiple peak shapes can be used,
see the documentation for the individual fit functions to see how they relate to the effective
values displayed in the diagnostic tables. For Gaussian
and
Lorentzian
, the widths and resolution are converted to values that
can be directly compared with the results of
EstimateResolutionDiffraction v1.
Limiting Spectra Calibrated¶
Supplying StartWorkspaceIndex
and/or StopWorkspaceIndex
will limit the spectra that are fitted.
Only those that are fitted will exist in the output table, OutputCalibrationTable
.
CombineDiffCal can accept input of partial instrument calibration as the GroupedCalibration
and will copy all other values fom the PixelCalibration
.
In this mode, the CalibrationWorkspace
supplied to CombineDiffCal should still be the InputWorkspace
supplied to PDCalibration
.
Usage¶
Example  PDCalibration
# If you have an old calibration it can be used as the starting point
oldCal = 'NOM_calibrate_d72460_2016_05_23.h5'
# list of d values for diamond
dvalues = (0.3117,0.3257,0.3499,0.4205,0.4645,0.4768,0.4996,0.5150,0.5441,0.5642,0.5947,0.6307,.6866,.7283,.8185,.8920,1.0758,1.2615,2.0599)
LoadEventNexus(Filename='NOM_72460', OutputWorkspace='NOM_72460')
PDCalibration(InputWorkspace='NOM_72460',
TofBinning=[300,.001,16666.7],
PreviousCalibrationFile=oldCal,
PeakPositions=dvalues,
PeakWidthPercent=.008,
OutputCalibrationTable='cal',
DiagnosticWorkspaces='diag')
# Print the result
print("The calibrated difc at detid {detid} is {difc}".format(**mtd['cal'].row(40000)))
Output:
The calibrated difc at detid 40896 is 5523.060327692842
Example  PDCalibration with BackToBackExponential fit function
The following example shows how to use PDCalibration with the BackToBackExponential fit function. The fit works best if sensible initial values for the parameters are specified in an instrument definition or parameter file (for more details, see the fitting parameters documentation):
Load(Filename=r'ENGINX00193749.nxs', OutputWorkspace='193749')
dpks = (1.913220892, 1.631600313,
1.562138267, 1.352851554, 1.104598643)
# initial values for GSAS parameters A, B, S are in ENGINX parameters .xml
# use log binning
PDCalibration(InputWorkspace='193749',
TofBinning=[10000,0.0005,46000],
PeakPositions=dpks,
PeakWindow = 0.03,
MinimumPeakHeight = 0.5,
PeakFunction = 'BackToBackExponential',
CalibrationParameters = 'DIFC',
OutputCalibrationTable='cal_B2B_DIFC_chisqTrue',
DiagnosticWorkspaces = 'diag_B2B_DIFC_chisqTrue',
UseChiSq = True)
# Print the result
print("The calibrated difc at detid {detid} is {difc}".format(**mtd['cal_B2B_DIFC_chisqTrue'].row(1000)))
Output:
The calibrated difc at detid 108041 is 16834.952770921267
Categories: AlgorithmIndex  Diffraction\Calibration
Source¶
C++ header: PDCalibration.h
C++ source: PDCalibration.cpp