orGUI: Orientation and Integration with 2D detectors

Introduction

orGUI is a software that can be used to determine the orientation of single crystal samples in X-ray diffraction experiments from the observation of few reflections on a large, statinary 2D detector. The settings of a 4-circle sample positioning stage as used for surface X-ray diffraction can be calculated. 

Intensity integration is possible along arbitrary direcrions in reciprocal space.  

Its primary usecase is High Energy Surface X-ray diffraction (HESXRD) or Transmission Surface diffraction.

Installation

orGUI is available on PyPi. To install orGUI (and all its dependencies) from pypi, run:

pip install orGUI[full]

To install orGUI with a minimal set of dependencies, run:

pip install orGUI

To directly install the files downloaded from this repository, run on the top level with the pyproject.toml

pip install .

Getting started

*orGUI* can be started by the shell command `orGUI`. *orGUI* can also be started preconfigured with a configuration file <configfile> by typing

orGUI <configfile>
   
All configuration is accessible in the user interface in the menu `Config->Machine parameters` and `Config->Crystal parameters`. 
Examples of configuration files are provided with the source code in this repository.

*orGUI* is designed to handle data, which is saved in a  NEXUS format or a combination of `SPEC <https://certif.com/spec.html>`_ files and separately saved image files. 
The file browser on the left side of orGUI shows the contents of the NEXUS or SPEC file, which typically contain multiple scans. Double clicking a scan in the file browser will open the specified scan.

Data is typically saved differently (i.e. counter names, image locations, etc.) at different beamlines. Backends for loading scan data currently only exists for ID31 at the ESRF and P21.2 at DESY. 
Loading data from other beamlines requires writing a new backend, which handles the loading of the scan data. The backends are located in `orgui/backend` of the source directory. 
Documentation about writing new backends will follow in a future release. Please create an issue on Github or write an Email for help on writing a new backend.

A simplistic backend for loading of bare image data without meta data information is available under `file->Generate scan from images`. 

Description 

Here is a simplistic description of the usual workflow for crystal truncation rod integration (a more complete manual will follow): 

orGUI uses the diffractometer convention by Lohmeier & Vlieg 1993 (https://doi.org/10.1107/S0021889893004868). However, the phi-circle rotates around the y-axis instead of the z-axis!. The azimuth angle in "machine parameters" rotates the whole diffractometer around the primary beam direction. Also theta = -omega. (Since at ID31 this rotation is right-handed). The detector geometry of orGUI is adapted from the commonly used python package pyFAI, which enables comprehensive detector geometry calibration.
It is recommended to determine the position of the X-ray detector from the Debye-Scherrer rings of a X-ray diffraction calibration standard such as CeO2 with the geometry calibration tools of pyFAI.
The resulting `poni` file can currently only be loaded in orGUI by setting the `poni` parameter in the `Machine` section of the orGUI config file to the poni file location. The orGUI config file must then be loaded.

For setting the orientation matrix, there are 2 methods available:

1. Expert mode: This is in the menu Reciprocal Space -> Edit orientation matrix. This is more intended to be used if symmetries can be directly observed at specific angle settings and applies more to Transmission Diffraction (e.g. if you see that two Bragg reflections have identical intensities, a reference position can be obtained from that). This is not really extremely useful for Grazing incidence geometry since you have to think about what you are doing.

2. Conventional setting of matrix using reference reflections (Busing & Levy):

The images and the window "Reciprocal space navigation" is used for that. Double clicking at any position in the image will set a red reference reflection at this specific image. The position of the marker on the image defines the scattering angles and the image number gives the sample rotation angle (i.e. theta) of the reference reflection. You can drag+drop the marker around in the image and the image number can be changed with the two buttons in the top right corner of the "Reciprocal space navigation" window (one button selects the current image for the chosen refllection; with the other you can jump to the image which was previously selected for the reflection). Usually the HKL values are wrong when you add a reflection. This can be overridden in the table in the Reciprocal space navigation window. To calculate the matrix click "calculate U".

This function also works with only one reference reflection by assuming that the L axis is pointing towards the z/azimuth-direction (Enable View->machine parameters to display a marker at the z-direction). For other geometries you need at least 2 reference reflections.

So what I ususally do is to search for a nicely visible reflection close to L = 0 (Either a Bragg reflection or a CTR at L = 0 usually work fine.)

When the matrix is set correctly, the calculated CTR reflections (Enable View->CTR reflections) should match up with the ones in the data when you change the active image.

To integrate a stationary scan (i.e. for each image, find the intersection of the CTR with the image and integrate a ROI around it), use hklscan in the ROI integration tab on the left side. To visualize the ROI on the image, enable View-> show ROI. Lorentz correction is not yet automatically applied here! Setting a pixel mask works by using the mask tool at the top of the image view (it is the mask icon).

There is now a also a rocking scan integration feature, which usually gives better integrated CTR, but is not yet optimized for computation time currently takes a long time to compute. 

Examples

Some examples of configuration files are provided in the examples folder.