Welcome to xrayutilities’s documentation!¶

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

This documentation can also be downloaded in PDF format.

Installation¶

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.

Introduction¶

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

Overview¶

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. For details see the full API documentation of xrayutilities found here: Examples and API-documentation.

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)
    http://dx.doi.org/10.1088/0957-4484/22/42/425704
"""

import os

import matplotlib.pyplot as plt
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
datapath = os.path.join("examples", "data")

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

# 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(datapath, sample + ".h5")
try:
    s  # try if spec file object already exist ("run -i" in ipython)
except NameError:
    s = xu.io.SPECFile(sample + ".spec.bz2", path=datapath)
else:
    s.Update()
s.Save2HDF5(h5file)

#################################
# InP (333) reciprocal space map
omalign = 43.0529  # experimental aligned values
ttalign = 86.0733
[omnominal, _, _, 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
plt.figure()
cf = plt.contourf(gridder.xaxis, gridder.yaxis, INT, 100, extend='min')
plt.xlabel(r'$Q_{[11\bar2]}$ ($\mathrm{\AA}^{-1}$)')
plt.ylabel(r'$Q_{[\bar1\bar1\bar1]}$ ($\mathrm{\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.

Source Installation¶

Express instructions¶

install the dependencies (Windows: Python(x,y) or WinPython; 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:

> pip install .

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

Detailed instructions¶

Installing xrayutilities is done using Python’s setuptools

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 runtime dependencies are:

Python the scripting language in which most of xrayutilities code is written in. (>= 3.6, for Python 2.7 use xrayutilities 1.5.X or older)
Numpy a Python module providing numerical array objects (version >= 1.9)
Scipy a Python module providing standard numerical routines, which is heavily using numpy arrays (version >= 0.13.0)
h5py a powerful Python interface to HDF5.
lmfit a Python module for least-squares minimization with bounds and constraints (needed for fitting XRR/XRD data)

For several features optional dependencies are needed:

Matplotlib a Python module for high quality 1D and 2D plotting (optional, version >= 3.1.0)
IPython although not a dependency of xrayutilities the IPython shell is perfectly suited for the interactive use of the xrayutilities python package.
mayavi only used optionally in Crystal.show_unitcell where it produces a superior visualization to otherwise used Matplotlib 3D plots

Additionally, the following Python modules are needed when building xrayutilities from source or wanting to test your installation:

C-compiler Gnu Compiler Collection or any compatible C compiler. On windows you most probably want to use the Microsoft compilers.
Python development headers
setuptools build system
pytest needed for running the pre-configured unittest environment, which in principal can also be achieved only by the unittest package (optional)

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
sphinx_rtd_theme sphinx theme used
svglib library needed by rst2pdf to include svg images into the pdf documentation

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

Building and installing the library and python package¶

Although the setup.py script can be called manually its recommended to always use pip to install xrayutilities, which can be done by executing

>pip install .

or

>pip 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 the systems default directories (recommended).

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 package managers this should be 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 either Anaconda, Python(x,y) or WinPython Python distributions, which include already all of the needed dependencies for installing xrayutilities.

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 or using pip, otherwise one can follow the general installation instructions. On Anaconda it can also be done using the conda-forge *xrayutilities* package.

Examples and API-documentation¶