# 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

# 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: Etamples 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

xrayutilities provides a set of functions to read experimental data from various data file formats. All of them are gathered in the `xrayutilities.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 `xrayutilities.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 `xrayutilities.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

Calculation of angles needed to align Bragg reflections in various diffraction geometries is done using the Materials defined in the `xrayutilities.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 `xrayutilities.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 `xrayutilities.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.

     1"""
     2Example script to show how to use xrayutilities to read and plot
     3reciprocal space map scans from a spec file created at the ESRF/ID10B
     4
     5for details about the measurement see:
     6    D Kriegner et al. Nanotechnology 22 425704 (2011)
     7    http://dx.doi.org/10.1088/0957-4484/22/42/425704
     8"""
     9
    10import os
    11
    12import matplotlib.pyplot as plt
    13import xrayutilities as xu
    14
    15# global setting for the experiment
    16sample = "test"  # sample name used also as file name for the data file
    17energy = 8042.5  # x-ray energy in eV
    18center_ch = 715.9  # center channel of the linear detector
    19chpdeg = 345.28  # channels per degree of the linear detector
    20roi = [100, 1340]  # region of interest of the detector
    21nchannel = 1500  # number of channels of the detector
    22datapath = os.path.join("examples", "data")
    23
    24# intensity normalizer function responsible for count time and absorber
    25# correction
    26normalizer_detcorr = xu.IntensityNormalizer(
    27    "MCA",
    28    mon="Monitor",
    29    time="Seconds",
    30    absfun=lambda d: d["detcorr"] / d["psd2"].astype(float))
    31
    32# substrate material used for Bragg peak calculation to correct for
    33# experimental offsets
    34InP = xu.materials.InP
    35
    36# initialize experimental class to specify the reference directions of your
    37# crystal
    38# 11-2: inplane reference
    39# 111: surface normal
    40hxrd = xu.HXRD(InP.Q(1, 1, -2), InP.Q(1, 1, 1), en=energy)
    41
    42# configure linear detector
    43# detector direction + parameters need to be given
    44# mounted along z direction, which corresponds to twotheta
    45hxrd.Ang2Q.init_linear('z-', center_ch, nchannel, chpdeg=chpdeg, roi=roi)
    46
    47# read spec file and save to HDF5-file
    48# since reading is much faster from HDF5 once the data are transformed
    49h5file = os.path.join(datapath, sample + ".h5")
    50try:
    51    s  # try if spec file object already exist ("run -i" in ipython)
    52except NameError:
    53    s = xu.io.SPECFile(sample + ".spec.bz2", path=datapath)
    54else:
    55    s.Update()
    56s.Save2HDF5(h5file)
    57
    58#################################
    59# InP (333) reciprocal space map
    60omalign = 43.0529  # experimental aligned values
    61ttalign = 86.0733
    62[omnominal, _, _, ttnominal] = hxrd.Q2Ang(
    63    InP.Q(3, 3, 3))  # nominal values of the substrate peak
    64
    65# read the data from the HDF5 file
    66# scan number:36, names of motors in spec file: omega= sample rocking, gamma =
    67# twotheta
    68[om, tt], MAP = xu.io.geth5_scan(h5file, 36, 'omega', 'gamma')
    69# normalize the intensity values (absorber and count time corrections)
    70psdraw = normalizer_detcorr(MAP)
    71# remove unusable detector channels/regions (no averaging of detector channels)
    72psd = xu.blockAveragePSD(psdraw, 1, roi=roi)
    73
    74# convert angular coordinates to reciprocal space + correct for offsets
    75[qx, qy, qz] = hxrd.Ang2Q.linear(
    76    om, tt,
    77    delta=[omalign - omnominal, ttalign - ttnominal])
    78
    79# calculate data on a regular grid of 200x201 points
    80gridder = xu.Gridder2D(200, 201)
    81gridder(qy, qz, psd)
    82# maplog function limits the shown dynamic range to 8 orders of magnitude
    83# from the maxium
    84INT = xu.maplog(gridder.data.T, 8., 0)
    85
    86# plot the intensity as contour plot using matplotlib
    87plt.figure()
    88cf = plt.contourf(gridder.xaxis, gridder.yaxis, INT, 100, extend='min')
    89plt.xlabel(r'$Q_{[11\bar2]}$ ($\mathrm{\AA}^{-1}$)')
    90plt.ylabel(r'$Q_{[\bar1\bar1\bar1]}$ ($\mathrm{\AA}^{-1}$)')
    91cb = plt.colorbar(cf)
    92cb.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 (Mostly handled by pip, but you will need a C-compiler, see below for details).

> - 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 pip with the meson-python build backend.

The package can be installed on Linux, Mac OS X and Microsoft Windows. 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

  - meson-python 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

  - sphinx-pyproject sphinx configuration support for the pyproject.toml file

  - 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

The build of the C library as well as of the material properties database is performed using the meson-python build backend. The build should be trigger via pip, which from the source directory 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

xrayutilities should work with the most common Python distributions. If you use Anaconda, consider using the conda-forge *xrayutilities* package. Using Python(x,y), WinPython, or Python from www.python.org , the installation is easiest from the Python package index via pip install xrayutilities as described above.

For building from source Microsoft Visual C++ (MSVC) or mingw are supported, but you should use the same compiler used by your Python distribution.

# Etamples and API-documentation

- Examples
  - Reading data from data files
  - Angle calculation using `Experiment` and `materials` classes
  - Using the `Gridder` classes
  - Line cuts from reciprocal space maps
  - Using the `materials` subpackage
  - Calculation of diffraction angles for a general geometry
  - User-specific config file
  - Determining detector parameters
- Simulation examples
  - Building Layer stacks for simulations
  - Setting up a model
  - Reflectivity calculation and fitting
  - Diffraction calculation
  - Powder diffraction simulations

# Indices and tables

- Index

- Module Index

- Search Page