Manual Reflection Setting¶

The UB matrix describes how reciprocal lattice coordinates are oriented on the diffractometer. The B matrix is determined by the lattice constants and converts (h, k, l) from reciprocal lattice units to Cartesian reciprocal-space coordinates. The U matrix describes how the crystal is mounted relative to the diffractometer sample circles.

Reference-Reflection Method¶

The usual manual workflow is to determine U from one or more observed reference reflections:

Open a scan and display an image that contains a known reflection.
Double-click the reflection position in the image. This creates a reference marker in the Reciprocal space navigation window.
Move the marker if needed. The marker position defines the detector coordinates, and the selected image number defines the sample rotation angle for that observation.
Enter or correct the reflection h, k, and l values in the reference-reflection table.
Repeat for a second linearly independent reflection when possible.
Click Calculate U.

Two linearly independent reflections fully determine the orientation matrix. For the common surface-diffraction case, orGUI can also estimate an orientation from a single reference reflection by assuming that the L direction points toward the z/azimuth reference direction. This is useful for quick setup when a clear reflection near L = 0 is visible, but a two-reflection orientation is the more general procedure.

Reflection Edit Controls¶

The Reflection edit group in the Reciprocal space navigation panel contains the manual tools for adjusting the selected reference reflection.

search image: Displays the image assigned to the active reference reflection and centers the detector view on the reflection marker.
select Image: Assigns the currently displayed scan image to the active reference reflection. The image number is part of the measured diffractometer angle set, so this step changes the measured momentum-transfer vector.
2D peak search: Runs a local center-of-mass peak search around the current marker. The dialog first asks for a coarse detector ROI and scan-axis range, then uses the refined result as the start point for a finer search. If a detector mask is set, masked pixels are excluded.

Adding Calculated Bragg Reflections Manually¶

The Auto UB/Reflections group also contains add Bragg reflection. This is a semi-manual helper for cases where a usable UB matrix already exists. It calculates allowed Bragg reflections from the current crystal, detector calibration, scan range, and current UB matrix, then orders candidates by how much new reciprocal-space information they add relative to the already selected reference reflections.

The opened dialog lets the user step through the candidate list, jump to the predicted image, run the same local peak search used by the manual reflection tools, and accept selected candidates into the reference-reflection table. After accepting useful reflections, click Calculate U again to update the orientation matrix.

Expert Matrix Editing¶

The menu entry Reciprocal Space -> Edit orientation matrix opens the expert path for editing the matrix directly. This is intended for cases where the orientation can be inferred from known symmetry or from an already established experiment geometry. It is less forgiving than the reference-reflection method, especially in grazing-incidence geometries.

Validation¶

After calculating the matrix, enable View -> CTR reflections and step through the active scan. The calculated CTR or Bragg positions should follow the features in the detector images. If they do not, check the assigned hkl values, the selected image number of each reference reflection, the detector calibration, and the beamline scan-axis convention.

The underlying calculation follows the Busing and Levy orientation-matrix method adapted to the orGUI diffractometer geometry. The observed detector coordinates and scan angles define momentum-transfer vectors in the inner sample-circle frame; U is then obtained by matching those vectors to the corresponding reciprocal lattice vectors.

Reference-Reflection Mismatch Coloring¶

The reference-reflection table reports the mean mismatch between the measured momentum-transfer vectors and the vectors calculated from the current UB matrix. The angular mismatch \(\Delta\theta_i\) is the angle between the two vectors for reflection \(i\). The Q-norm mismatch \(\Delta Q_i\) is the absolute difference between their magnitudes, in \(\mathrm{\AA}^{-1}\).

Rows are colored in two steps. First, orGUI computes a relative mismatch ranking across the currently selected reference reflections. The angular mismatch \(\Delta\theta_i\) and the relative Q-norm mismatch \(\Delta Q_i / \lVert Q_{\mathrm{UB},i} \rVert\) are normalized independently over the current table:

\[r_{\theta,i} = \frac{ \Delta\theta_i - \min_j(\Delta\theta_j) }{ \max_j(\Delta\theta_j) - \min_j(\Delta\theta_j) },\]

\[r_{Q,i} = \frac{ \Delta Q_i / \lVert Q_{\mathrm{UB},i} \rVert - \min_j\left( \Delta Q_j / \lVert Q_{\mathrm{UB},j} \rVert \right) }{ \max_j\left( \Delta Q_j / \lVert Q_{\mathrm{UB},j} \rVert \right) - \min_j\left( \Delta Q_j / \lVert Q_{\mathrm{UB},j} \rVert \right) }.\]

If all finite values in one channel are equal, that normalized channel is set to zero for those finite rows. The relative color score is the mean of the two normalized channels:

\[r_i = \frac{1}{2}\left(r_{\theta,i} + r_{Q,i}\right).\]

This score maps the best current agreement to green and the worst current agreement to red. It is a comparative diagnostic within the current reference set, so it remains useful when the fit is not yet limited by instrumental resolution.

Second, orGUI checks whether an individual reflection is already within the local detector-pixel resolution. This is an absolute test, not a relative ranking. At the reflection pixel position \((x_i, y_i)\), orGUI evaluates the detector angle transform at the center pixel and at the two neighboring pixels:

\[\begin{split}\boldsymbol{\theta}_i &= \boldsymbol{\theta}(x_i, y_i), \\ \boldsymbol{\theta}_{x,i} &= \boldsymbol{\theta}(x_i + 1, y_i), \\ \boldsymbol{\theta}_{y,i} &= \boldsymbol{\theta}(x_i, y_i + 1),\end{split}\]

where \(\boldsymbol{\theta} = (\delta, \gamma)\) in radians. Because this absolute mismatch test reduces the detector response to a scalar score, the local angular size of one detector pixel uses the finer detector-axis resolution:

\[\theta_{\mathrm{pix},i} = \min\left( \left\lVert \boldsymbol{\theta}_{x,i} - \boldsymbol{\theta}_i \right\rVert, \left\lVert \boldsymbol{\theta}_{y,i} - \boldsymbol{\theta}_i \right\rVert \right).\]

This stricter choice avoids marking a reflection as pixel-resolved only because its mismatch fits within the coarser axis of a detector with non-square pixels.

Using the incident wavevector magnitude \(K\), this local angular tolerance is converted to a Q-norm tolerance:

\[Q_{\mathrm{pix},i} = K\,\theta_{\mathrm{pix},i}.\]

The pixel-equivalent mismatch score is

\[s_i = \max\left( \frac{\Delta\theta_i}{\theta_{\mathrm{pix},i}}, \frac{\Delta Q_i}{Q_{\mathrm{pix},i}} \right).\]

Thus \(s_i \le 1\) means that the reflection mismatch is within roughly one local detector pixel of the current instrumental angular resolution. The Resolution limit control in the reference-reflection panel sets the maximum allowed value of \(s_i\) for this absolute test. Reflections below that limit are marked blue to indicate that the agreement is resolution-limited. All other reflections keep the relative green-to-red coloring from \(r_i\).