Welcome to xrayutilities’s documentation!

Latest Version Git-repo on github Supported Python versions Development Status License Test status Test status Windows

If you look for downloading the package go to Sourceforge or GitHub (source distribution) or the Python package index (MS Windows binary).

Read more about xrayutilities below or in Journal of Applied Crystallography 2013, Volume 46, 1162-1170


The easiest way to install xrayutilities is using the Python package index version <https://pypi.python.org/pypi/xrayutilities> and execute

> pip install xrayutilities

If you prefer the installation from sources see the Source Installation below.


Mailing list and issue tracker

To get in touch with us or report an issue please use the mailing list or the Github issue tracker. When you want to follow announcements of major changes or new releases its recommended to sign up for the mailing list


xrayutilities is a collection of scripts used to analyze and simulate 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. Several models for the simulation of thin film reflectivity and diffraction curves are included.

In the following few 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. Following that the concept of how angular coordinates of Bragg reflections are calculated is presented. Before describing in detail the installation a minimal example for thin film simulations is shown.

Concept of usage

Flow diagram showing how to analyze x-ray diffraction data using xrayutilities

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.

A practical example showing the usage is given below.

Angle calculation using the material classes

Flow diagram showing how to calculate angular positions of Bragg reflection using xrayutilities

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.

hello world

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.

Example script to show how to use xrayutilities to read and plot
reciprocal space map scans from a spec file created at the ESRF/ID10B

for details about the measurement see:
    D Kriegner et al. Nanotechnology 22 425704 (2011)

import os

import matplotlib.pyplot as plt
import numpy
import xrayutilities as xu

# global setting for the experiment
sample = "test"  # sample name used also as file name for the data file
energy = 8042.5  # x-ray energy in eV
center_ch = 715.9  # center channel of the linear detector
chpdeg = 345.28  # channels per degree of the linear detector
roi = [100, 1340]  # region of interest of the detector
nchannel = 1500  # number of channels of the detector

# intensity normalizer function responsible for count time and absorber
# correction
absfun = lambda d: d["detcorr"] / d["psd2"].astype(numpy.float)
normalizer_detcorr = xu.IntensityNormalizer(

# substrate material used for Bragg peak calculation to correct for
# experimental offsets
InP = xu.materials.InP

# initialize experimental class to specify the reference directions of your
# crystal
# 11-2: inplane reference
# 111: surface normal
hxrd = xu.HXRD(InP.Q(1, 1, -2), InP.Q(1, 1, 1), en=energy)

# configure linear detector
# detector direction + parameters need to be given
# mounted along z direction, which corresponds to twotheta
hxrd.Ang2Q.init_linear('z-', center_ch, nchannel, chpdeg=chpdeg, roi=roi)

# read spec file and save to HDF5-file
# since reading is much faster from HDF5 once the data are transformed
h5file = os.path.join("data", sample + ".h5")
    s  # try if spec file object already exist ("run -i" in ipython)
except NameError:
    s = xu.io.SPECFile(sample + ".spec", path="data")

# InP (333) reciprocal space map
omalign = 43.0529  # experimental aligned values
ttalign = 86.0733
[omnominal, dummy, dummy, ttnominal] = hxrd.Q2Ang(
    InP.Q(3, 3, 3))  # nominal values of the substrate peak

# read the data from the HDF5 file
# scan number:36, names of motors in spec file: omega= sample rocking, gamma =
# twotheta
[om, tt], MAP = xu.io.geth5_scan(h5file, 36, 'omega', 'gamma')
# normalize the intensity values (absorber and count time corrections)
psdraw = normalizer_detcorr(MAP)
# remove unusable detector channels/regions (no averaging of detector channels)
psd = xu.blockAveragePSD(psdraw, 1, roi=roi)

# convert angular coordinates to reciprocal space + correct for offsets
[qx, qy, qz] = hxrd.Ang2Q.linear(
    om, tt,
    delta=[omalign - omnominal, ttalign - ttnominal])

# calculate data on a regular grid of 200x201 points
gridder = xu.Gridder2D(200, 201)
gridder(qy, qz, psd)
# maplog function limits the shown dynamic range to 8 orders of magnitude
# from the maxium
INT = xu.maplog(gridder.data.T, 8., 0)

# plot the intensity as contour plot using matplotlib
cf = plt.contourf(gridder.xaxis, gridder.yaxis, INT, 100, extend='min')
plt.xlabel(r'$Q_{[11\bar2]}$ ($\AA^{-1}$)')
plt.ylabel(r'$Q_{[\bar1\bar1\bar1]}$ ($\AA^{-1}$)')
cb = plt.colorbar(cf)
cb.set_label(r"$\log($Int$)$ (cps)")

More such examples can be found on the Examples page.

X-ray diffraction and reflectivity simulations

xrayutilties includes a database with optical properties of materials and therefore simulation of reflectivity and diffraction data can be accomplished with relatively litte additional input. When the stack of layers is defined along with the layer thickness and material several models for calculation of X-ray reflectivity and dynamical/kinematical X-ray diffraction are provided.

A minimal example for an AlGaAs superlattice structure is shown below. It shows how a basic stack of a superlattice is built from its ingredients and how the reflectivity and dynamical diffraction model are initialized in the most basic form:

import xrayutilities as xu
# Build the pseudomorphic sample stack using the elastic parameters
sub = xu.simpack.Layer(xu.materials.GaAs, inf)
lay1 = xu.simpack.Layer(xu.materials.AlGaAs(0.25), 75, relaxation=0.0)
lay2 = xu.simpack.Layer(xu.materials.AlGaAs(0.75), 25, relaxation=0.0)
pls = xu.simpack.PseudomorphicStack001('pseudo', sub+10*(lay1+lay2))
# simulate reflectivity
m = xu.simpack.SpecularReflectivityModel(pls, sample_width=5, beam_width=0.3)
alphai = linspace(0, 10, 1000)
Ixrr = m.simulate(alphai)
# simulate dynamical diffraction curve
alphai = linspace(29, 38, 1000)
md = xu.simpack.DynamicalModel(pls)
Idyn = md.simulate(alphai, hkl=(0, 0, 4))

More detailed examples and description of model parameters can be found on the Simulation examples page or in the examples directory.

xrayutilities Python package

xrayutilities is a Python package for assisting with x-ray diffraction experiments. Its the python package included in *xrayutilities*.

It helps with planning experiments as well as analyzing the data.

Authors:Dominik Kriegner <dominik.kriegner@gmail.com> and Eugen Wintersberger <eugen.wintersberger@desy.de>

for more details see the full API documentation of xrayutilities found here: Examples and API-documentation.

Source Installation

Express instructions

  • install the dependencies (Windows: pythonxy; Linux/Unix: see below for dependencies).
  • download xrayutilities from here or use git to check out the latest version.
  • open a command line and navigate to the downloaded sources and execute:
> python setup.py install

which will install xrayutilities to the default directory. It should be possible to use it (import xrayutilities) from now on in python scripts.


The python package of xrayutilities was formerly called ‘’xrutils’‘

Detailed instructions

Installing xrayutilities is done using Python’s distutils

The package can be installed on Linux, Mac OS X and Microsoft Windows, however, it is mostly tested on Linux/Unix platforms. Please inform one of the authors in case the installation fails!

Required third party software

To keep the coding effort as small as possible xrayutilities depends on a large number of third party libraries and Python modules.

The needed dependencies are:
  • C-compiler Gnu Compiler Collection or any compatible C compiler. On windows you most probably want to use the Microsoft compilers.
  • HDF5 a versatile binary data format (library is implemented in C). Although the library is not called directly, it is needed by the h5py Python module (see below).
  • Python the scripting language in which most of xrayutilities code is written in. (version 2.7 or >= 3.2)
  • git a version control system used to keep track on the xrayutilities development. (only needed for development)
Additionally, the following Python modules are needed in order to make xrayutilities work as intended:
  • Numpy a Python module providing numerical array objects (version >= 1.8)
  • Scipy a Python module providing standard numerical routines, which is heavily using numpy arrays (version >= 0.11.0)
  • h5py a powerful Python interface to HDF5.
  • Matplotlib a Python module for high quality 1D and 2D plotting (optionally)
  • lmfit a Python module for least-squares minimization with bounds and constraints (optionally needed for fitting XRR data)
  • IPython although not a dependency of xrayutilities the IPython shell is perfectly suited for the interactive use of the xrayutilities python package.
For building the documention (which you do not need to do) the requirements are:
  • sphinx the Python documentation generator
  • numpydoc sphinx-extension needed to parse the API-documention
  • rst2pdf pdf-generation using sphinx

After installing all required packages you can continue with installing and building the C library.

Building and installing the library and python package

xrayutilities uses the distutils packaging system to build and install all of its components. You can perform the installation by executing

>python setup.py install


>python setup.py install --prefix=INSTALLPATH

in the root directory of the source distribution.

The –prefix option sets the root directory for the installation. If it is omitted the libary is installed under /usr/lib/ on Unix systems or in the Python installation directory on Windows.

Setup of the Python package

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

>export PYTHONPATH=$PYTHONPATH:<local install path>/lib64/python2.7/site-packages

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 Python(x,y) this is done automatically). Be sure to use the correct directory which might be similar to

<local install path>/Lib/site-packages

on Windows systems.

Notes for installing on Windows

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.

Examples and API-documentation

Indices and tables