4. Correcting for sample misalignment

When mounting your sample on a spectrometer, it can often be the case that it is slightly misaligned with respect to the ‘perfect’ alignment assumed when generating the SQW file (the direction of u and v vectors provided in gen_sqw and accumulate_sqw, where u is parallel to the beam and v defines the sample rotation plain). It is straightforward to correct this misalignment, once enough data have been accumulated, by comparing the positions of Bragg peaks with what they are expected to be.

Alignment correction is a two-step process:

  1. First, the misalignment must be determined and checked.

  2. Then, the correction must be applied to the data.

4.1. Step 1 - determining the true Bragg peak positions

4.1.1. Bragg Positions

First you should identify several Bragg peaks which are strong and not parallel along \(\{p \in{} P: \Gamma{}\rightarrow{}p\}\) in your data, where \(\{P\}\) is the set of Bragg peaks, where \(\Gamma{}\rightarrow{}p\) is the path from the gamma point (\([0,0,0]\)) to the point \(p\).

Henceforth, we define \(\{\vec{Q}\}\) as the set of vectors from the gamma point to each Bragg point \(\{p \in{} P: \vec{\Gamma{}p}\}\).

The following routine generates radial and transverse cuts around specified Bragg peaks and calculates the deviation from the expected values.

[rlu_actual, widths, wcut, wpeak] = bragg_positions (sqw_obj, bragg_expected, ...
                radial_cut_length, radial_bin_width, radial_thickness,...
                trans_cut_length, trans_bin_width, trans_thickness, ...
                energy_window, <keyword options>)

The inputs are:

  • sqw_obj - sqw object with misaligned data

  • bragg_expected - an n-by-3 array specifying the Bragg positions expected from aligned crystal.

  • radial_cut_length - lengths of the various cuts along each of \(\{\vec{Q}\}\).

  • radial_bin_width - bin (step) sizes along the radial cuts

  • radial_thickness - integration thickness along the axes perpendicular to the radial cut direction

  • trans_cut_length - lengths of cuts of each cut perpendicular to \(\{\vec{Q}\}\).

  • trans_bin_width - bin (step) sizes along the transverse cuts

  • trans_thickness - integration thickness along the two perpendicular directions to the transverse cuts

  • energy_window - Energy integration window around elastic line (meV). Choose according to the instrument resolution.

Note

This is the full energy window. A good value for energy_window is 2 x full-width half-height, e.g. for -1meV to +1 meV, set energy_window=2

The following keyword options are available:

For binning:

  • 'bin_absolute' [Default] - denotes that the radial and transverse cut lengths, bin sizes, and thicknesses are in inverse Angstroms

  • 'bin_relative' - denotes that cut lengths, bin sizes and thicknesses are fractions of \(\left|\mathbf{Q}\right|\) for radial cuts and degrees for transverse cuts.

For fitting:

  • 'outer' [Default] - determines peak position from centre of peak half-height by finding the peak width moving inwards from the limits of the data

Note

Useful if there is known to be a single peak in the data as it is more robust to too finely binned data.

  • 'inner' - determines the peak position from centre of peak half height by finding the peak width moving outwards from peak maximum

  • 'gaussian' - fits a Gaussian on a linear background.

The outputs are:

  • rlu_actual - the actual peak positions as an n-by-3 matrix in \(h,k,l\) as indexed with respect to the current lattice parameters.

  • widths - an n-by-3 array containing the FWHH in Ang^-1 of the peaks along each of the three projection axes

  • wcut - an n-by-3 array of cuts, along three orthogonal directions through each Bragg point from which the peak positions were determined.

Note

These cuts are IX_dataset_1d objects and can be plotted using the plot functions.

  • wpeak - an n-by-3 array of spectra, that summarise the peak analysis.

Note

These cuts are IX_dataset_1d objects and can be plotted using the plot functions.

Note

wcut and wpeak can be passed to bragg_positions_view to view the output.

4.1.2. Step 2 - check the Bragg positions fits worked properly

You can make plots of the cuts and fits of your predicted Bragg peaks to check that the program has correctly fitted everything, using outputs from bragg_positions described above.

bragg_positions_view(wcut,wpeak)

You will be prompted in the MATLAB command window as to which plot and fit you wish to view.

Note

Press 'q' to exit this interactive mode.

Warning

It is important to use this function to scrutinise the peaks and the fits because there many parameters that may need adjusting depending on the degree of misalignment of your crystal: the length, binning and thicknesses of the cuts you specified in bragg_positions, the quality of the cuts (for example the Bragg peaks may be near gaps in the detectors so the cuts are poorly defined), the Bragg peaks may have strange shapes which can confuse the automatic fitting, etc.

4.1.3. Step 3 - calculate the misalignment correction

Using the outputs of bragg_positions, you can determine a transformation to go from the original misaligned frame to the aligned frame.

alignment_info = refine_crystal(rlu_actual, alatt, angdeg, rlu_expected, <keyword options>);

The inputs are:

  • rlu_actual - the an n-by-3 matrix of actual peak positions as in \(h,k,l\) as indexed with the current lattice parameters

  • alatt, angdeg - the lattice parameters and angles used in the original (misaligned) sqw file.

  • rlu_expected - the predicted (integer) Bragg peaks corresponding to bragg_expected

The keyword options are:

  • fix_lattice - Fix all lattice parameters \([a,b,c,\alpha,\beta,\gamma]\), i.e. only allow crystal orientation to be refined

  • fix_alatt - Fix \([a,b,c]\), but allow lattice angles \([\alpha,\beta,\gamma]\) to be refined together with the crystal orientation

  • fix_angdeg - Fix \([\alpha,\beta,\gamma]\), but allow the lattice parameters \([a,b,c]\) to be refined together with crystal orientation

  • fix_alatt_ratio Fix the ratio of the lattice parameters as given by the values in the inputs, but allow the overall scale of the lattice to be refined together with crystal orientation

  • fix_orient - Fix the crystal orientation i.e. only refine the lattice parameters

  • free_alatt - Array length 3 of booleans, 1=free, 0=fixed

    e.g. 'free_alatt',[0,1,0],... allows only lattice parameter \(b^{*}\) to vary

  • free_angdeg - Array length 3 of booleans, 1=free, 0=fixed.

    e.g. 'free_angdeg',[1,1,0],... fixes lattice angle gamma buts allows \(\alpha\) and \(\beta\) to vary

Note

To achieve finer control of the refinement of the lattice parameters, use free_alatt and free_angdeg

The output is an crystal_alignment_info object which contains all the relevant data for crystal realignment, namely the rotation matrix which aligns Crystal Cartesian frame into correct position and modified lattice parameters, if refine_crystal modified them.

4.1.4. Step 4 - apply the correction to the data

There are different to do this, for different circumstances:

  • When you have a completed scan and an existing sqw file:

    Apply the correction to an existing file

  • When you have a loaded sqw object:

    Apply the correction to the object. The object’s lattice and pixels orientation will be modified to aligned values.

  • When you are still accumulating data (e.g. on the beamline):

    Calculate what the goniometer offsets for regeneration

4.2. Option 1 : apply the correction to an existing sqw file

There is a simple routine to apply the changes to an existing file, without the need to regenerate it from raw data

change_crystal(win, alignment_info)

where alignment_info was determined in the steps described above. This procedure modifies lattice parameters and the pixels will be aligned whenever they are loaded or manipulated (e.g. accessing pixel data, cutting, plotting, etc.).

Once you have confirmed that the alignment you have is the correct one, it is possible to fix the alignment to avoid this calculation step.

This is done through the finalize_alignment function:

[wout, rev_corr] = finalize_alignment(win, ['-keep_original'])

Warning

You must have attached the alignment to the sqw through the change_crystal function prior to applying it.

Where:

  • win - Input filename or sqw object to update.

  • '-keep_original' - In the case of a file-backed sqw object, this will avoid overwriting the original datafile and retain the temporary file created as part of the calculation process

Note

If you use '-keep_original' you may wish to save your object as the temporary file will be cleared when the wout object is. (see: file_backed_objects)

  • wout - Resulting sqw object to which the alignment was applied. If input was kept in file or was filebacked, the object will be filebacked.

  • rev_corr - A corresponding crystal_alignment_info to be able to reverse the application.

Note

Finalize alignment of large sqw object may take substantial time. The time may be even bigger than regenerating this file from scratch as parallel generation is currently possible for sqw files generation but not yet implemented for finalize_alignment.

4.3. Option 2 : calculate goniometer offsets for regeneration of sqw file(s)

In this case there is a single routine to calculate the new goniometer offsets, that can then be used in future sqw file generation.

[alatt, angdeg, dpsi_deg, gl_deg, gs_deg] = crystal_pars_correct(u, v, alatt0, angdeg0, omega0_deg, dpsi0_deg, gl0_deg, gs0_deg, alignment_info, <keyword options>)

The inputs are:

  • u, v - Two 3-vectors which were used to define the notional scattering plane before any alignment corrections were performed.

Note

u is usually defined as the vector of the incident beam and v is coplanar with respect to the instrument.

  • alatt0, angdeg0 - The initial sample lattice parameters, before refinement

  • omega0_deg, dpsi0_deg, gl0_deg, gs0_deg - The initial goniometer offsets, before refinement (all in \(^\circ\))

Note

\(\text{d}\psi\), \(g_l\) and \(g_s\) refer to the Euler angles relative to the scattering plane. Naming conventions may differ in other notations, e.g. \(\theta, \phi, \chi\).

  • alignment_info - The crystal_alignment_info object determined above.

The keywords options are:

Warning

Normally these need not be given and the inputs u, v and omega will be used.

  • u_new, v_new - \(\vec{u}\), \(\vec{v}\) that define the scattering plane. \(d\psi\), \(g_{l}\), \(g_{s}\) will be calculated with respect to these vectors. (Default: u, v respectively)

  • omega_new - Value for the orientation of the virtual goniometer arcs. \(d\psi\), \(g_{l}\), \(g_{s}\) will be calculated with respect to this offset angle. (Default: omega) (\(^\circ\))

The outputs are:

  • alatt, angdeg - The true lattice parameters: \([a_{true},b_{true},c_{true}]\), \([\alpha_{true},\beta_{true},\gamma_{true}]\) (in Å and \(^\circ\) respectively)

  • dpsi_deg, gl_deg, gs_deg - Misorientation angles of the vectors u_new and v_new (all in \(^\circ\))

4.4. Option 2a (for use with e.g. Mslice): calculate the true u and v for your misaligned crystal

Following option 2 above, you can recalculate the true u and v vectors with the following method:

[u_true, v_true, rlu_corr] = uv_correct(u, v, alatt0, angdeg0, omega_deg, dpsi_deg, gl_deg, gs_deg, alatt_true, angdeg_true)

The inputs are:

  • u, v - the orientation of the correctly aligned crystal.

  • alatt, angdeg - the lattice parameters of the aligned crystal, i.e. the output of crystal_pars_correct.

  • omega_deg, dpsi_deg, gl_deg, gs_deg - the calculated misorientation angles, i.e. the output of crystal_pars_correct.

  • alatt_true, angdeg_true - similarly, the calculated correct lattice parameters

The outputs are:

  • u_true, v_true - the corrected \(\vec{u}\) and \(\vec{v}\) for e.g. Mslice.

  • rlu_corr - the orientation correction matrix to go from the notional to the real crystal (see above)

4.4.1. List of alignment correction routines

Below we provide a brief summary of the routines available for different aspects of alignment corrections. For further information type

help <function name>

in the Matlab command window.

4.5. bragg_positions

[rlu0,width,wcut,wpeak] = bragg_positions(w, rlu, radial_cut_length, radial_bin_width, radial_thickness,...
                                          trans_cut_length, trans_bin_width, trans_thickness)

Get actual Bragg peak positions, given initial estimates of their positions, from an sqw object or file

4.6. bragg_positions_view

bragg_positions_view(wcut, wpeak)

View the output of fitting to Bragg peaks performed by bragg_positions

4.7. crystal_pars_correct

[alatt, angdeg, dpsi_deg, gl_deg, gs_deg] = crystal_pars_correct(u, v, alatt0, angdeg0, omega0_deg, dpsi0_deg, gl0_deg, gs0_deg, al_info)

Return correct lattice parameters and crystal orientation for gen_sqw from a matrix that corrects the r.l.u.

4.8. refine_crystal

al_info = refine_crystal(rlu0, alatt0, angdeg0, bragg_peaks, [fix_])

Refine crystal orientation and lattice parameters

4.9. ubmatrix

[ub, mess, umat] = ubmatrix (u, v, b)

Calculate UB matrix that transforms components of a vector given in r.l.u. into the components in an orthonormal frame defined by the two vectors u and v (each given in r.l.u)

4.10. uv_correct

[u_true, v_true, rlu_corr] = uv_correct (u, v, alatt0, angdeg0, omega_deg, dpsi_deg, gl_deg, gs_deg, alatt_true, angdeg_true)

Calculate the correct u and v vectors for a misaligned crystal, for use e.g. with Mslice.

4.11. rlu_corr_to_lattice

[alatt,angdeg,rotmat,ok,mess]=rlu_corr_to_lattice(rlu_corr,alatt0,angdeg0)

Extract lattice parameters and orientation matrix from r.l.u correction matrix and reference lattice parameters