xrayutilities is a collection of scripts used to analyze x-ray diffraction data. It consists of a python package and several routines coded in C.
It especially useful for the reciprocal space conversion of diffraction data taken with linear and area detectors.

In the following two concepts of usage for the xrayutilities package will be described.
First one should get a brief idea of how to analyze x-ray diffraction data with xrayutilities.
After that the concept of how angular coordinates of Bragg reflections are calculated is presented.

xrayutilities provides a set of functions to read experimental data from various data file formats.
All of them are gathered in the io-subpackage.
After reading data with a function from the io-submodule the data might be corrected for monitor counts and/or absorption factor of a beam attenuator.
A special set of functions is provided to perform this for point, linear and area detectors.

Since the amount of data taken with modern detectors often is too large to be able to work with them properly, a functions for reducing the data from linear and area detectors are provided.
They use block-averaging to reduce the amount of data.
Use those carefully not to loose the features you are interested in in your measurements.

After the pre-treatment of the data, the core part of the package is the transformation of the angular data to reciprocal space.
This is done as described in more detail below using the experiment-module`.
The classes provided within the experiment module provide routines to help performing X-ray diffraction experiments.
This includes methods to calculate the diffraction angles (described below) needed to align crystalline samples and to convert data between angular and reciprocal space.
The conversion from angular to reciprocal space is implemented very general for various goniometer geometries.
It is especially useful in combination with linear and area detectors as described in this article.
In standard cases, Users will only need the initialized routines, which predefine a certain goniometer geometry like the popular four-cirlce and six-circle geometries.

After the conversion to reciprocal space, it is convenient to transform the data to a regular grid for visualization.
For this purpose the gridder-module has been included into xrayutilities.
For the visualization of the data in reciprocal space the usage of matplotlib is recommended.

Calculation of angles needed to align Bragg reflections in various diffraction geometries is done using the Materials defined in the materials-package.
This package provides a set of classes to describe crystal lattices and materials.
Once such a material is properly defined one can calculate its properties, which includes the reciprocal lattice points, lattice plane distances, optical properties like
the refractive index, the structure factor (including the atomic scattering factor) and the complex polarizability.
These atomic properties are extracted from a database included in xrayutilities.

Using such a material and an experimental class from the experiment-module, describing the experimental setup, the needed diffraction angles can be calculated for certain coplanar diffraction (high, low incidence), grazing incidence diffraction and also special non-coplanar diffraction geometries.
In the predefined experimental classes fixed geometries are used. For angle calculation of custom geometries using arbitrary geometries (max. of three free angles) the q2ang_fit-module can be used as described in one of the included example files.

A first example with step by step explanation is shown in the following.
It showcases the use of xrayutilities to calculate angles and read a scan recorded with a linear detector from spec-file and plots
the result as reciprocal space map using matplotlib.

You need to make your Python installation aware of where to look for the module.
This is usually only needed when installing in non-standard <install path> locations.
For this case append the installation directory to your PYTHONPATH environment variable by

on a Unix/Linux terminal. Or, to make this configuration persistent append this line to
your local .bashrc file in your home directory.
On MS Windows you would like to create a environment variable in the
system preferences under system in the advanced tab (Using pythonxy this is done automatically).
Be sure to use the correct directory which might be similar to

Since there is no packages manager on Windows the packages need to be installed manual
(including all the dependecies) or a pre-packed solution needs two be used. We strongly suggest to
use the Python(x,y) or
WinPython python distributions,
which include already all of the needed dependencies for installing xrayutilities.

The setup of the environment variables is also done by the python distributions.
One can proceed with the installation of xrayutilities directly!
The easiest way to do this on windows is to use the binaries distributed on the Python package index, otherwise one can follow the general installation instructions.
Depending on your compiler on Microsoft Windows it might be necessary to perform the building of the Python extension separately and specify the compiler manually.
This is done by

python setup.py build -c <compiler_name>

Using Python(x,y) you want to specify ‘mingw32’ as compiler name. With the WinPython it
is recommended to use the MS Visual Studio Express 2008 (which is freely available for download)
and can also build the code for 64bit Windows. In this case us ‘msvc’ as compiler name.

In case you want to do it the hard way install all of the following (versions in brackets indicate the tested set of versions by the author (2.3.2012)):

MinGW (0.4alpha)

Python (2.7.2)

numpy (1.6.1)

scipy (0.10.1)

numexpr (1.4.2) needed for pytables

pytables (2.3.1)

matplotlib (1.1.0)

It is suggested to add the MinGW binary directory, as well as the Python and Python-scripts directory
to the Path environment variable as described above! Installation is done as described above.