<img src="https://raw.githubusercontent.com/bjheinen/LiquidDiffract/master/LiquidDiffract/resources/icons/logo.png"> A graphical application for total X-ray scattering analysis of liquids and amorphous solids. LiquidDiffract can calculate and refine the normalised structure factor and real-space correlation functions, and extract structural information such as average bond lengths, coordination number, and density.

Maintainer

Benedict J. Heinen (benedict.heinen@gmail.com)

Citing LiquidDiffract

LiquidDiffract is described in an open access paper published in Physics and Chemistry of Minerals:

Heinen, B. J., & Drewitt, J. W. (2022). LiquidDiffract: Software for liquid total scattering analysis. Physics and Chemistry of Minerals, 49:9. doi:10.1007/s00269-022-01186-6

Please cite this article if you use LiquidDiffract in your work.

Requirements
Installation
Usage
References
License

Requirements

We recommend Python >= 3.10, and the latest available versions of the required packages. LiquidDiffract should run with earlier versions of these python packages but testing is limited. LiquidDiffract is system-independent and has been tested on Linux, Mac, and Windows. Dependencies are handled automatically when installing with pip. *LiquidDiffract supports multiple Qt bindings (PyQt5, PyQt6, PySide2, PySide6). Use the QT_API environment variable to run with a specifi API, otherwise the software will default to PyQt6 if available.

Installation

The simplest way to install LiquidDiffract is directly from PyPI with pip:

$ python3 -m pip install LiquidDiffract (on Windows use: py -m pip install LiquidDiffract)

The source code is directly available here

You can also use pip to install from a local directory.

<details><summary>Development installation</summary>

You can make a development (editable) install by using pip's -e flag:

$ pip install -e git+https://github.com/bjheinen/LiquidDiffract#egg=LiquidDiffract

You can also clone the git repo or download the source directly and install from a local directory:

$ cd /path/to/local/directory/
$ curl -Lo LiquidDiffract.zip https://github.com/bjheinen/LiquidDiffract/archive/master.zip
$ unzip LiquidDiffract.zip 
$ mv LiquidDiffract-*/ LiquidDiffract/
$ pip install -e /path/to/local/directory/LiquidDiffract/

It is useful if you want to make changes to the source code without having to re-install. Use Python's site-packages directory as the deployment directory if you want your editable install of LiquidDiffract available on your sys.path for other programs using your Python installation. To do this from the github page use the -t flag -t /path/to/directory

To run the test suite, do:

$ python -m unittest discover -v -s ./tests

Some tests are skipped in using Python<3.9, or Scipy<1.11.0

</details>

Usage

Loading the GUI

To run the software use the command

$ LiquidDiffract

If this fails setuptools may have placed the script in a directory not on your path. The location is usually a user or python specific scripts/bin folder, e.g. /usr/local/bin, ~/anaconda3/bin/, or Python\Python311\Scripts\

Alternatively, run 'ld_launcher.py' from the scripts folder of the installation directory $ python ld_launcher.py

Basic Usage

There are four main tabs which provide a selection of toolboxes for data operations at different stages of the workflow.

Background scaling/subtraction
Data operations: structure factor calculation, interference function optimisation, and density refinement
PDF calculation and data output
Estimation of coordination numbers and bond lengths (integration and curve-fitting)

Data are automatically plotted and tabs updated as operations are made. The graphical plots display coordinates in the upper-right corner. Click and drag or use the scroll-wheel to zoom in on a region. Double right-click to reset the view.

Background Subtraction Tab

This tab allows data and (optionally) background files to be loaded in. The auto-scale feature speeds up workflow but is not recommended for a close fit.

All data must be in Q-space. A toolbox is provided to convert raw experimental data of 2θ values to Q-space. By default LiquidDiffract expects data in inverse Angstroms, but an option to change this to inverse nano-metres is available in the Additional Preferences dialog, which is accessible from the Tools menu.

Data corrections such as a shift to account for fluorescence or attenuation from self-shielding (currently for slab-geometry only [28]) can also be applied here.

Refinement Tab

This is the tab where most of the data processing takes place.

The sample composition can be set here, along with data processing options. After setting these options the interference function i(Q) is calculated and displayed. i(Q) is related to the total molecular structure factor as:

i(Q)=S(Q)-1~~~\text{or}~~~i(Q)=S(Q)-S_{\infty}

depending on the formalism used.

This function can then be normalised by minimising errors in the real-space 'differential correlation function', D(r):

D(r)=\frac{2}{\pi}\int_{0}^{Q_\rm{{max}}}Qi(Q)\sin(Qr) dq

In LiquidDiffract the integral in the function D(r) is calculated by taking the imaginary portion of the inverse Fourier transform of Qi(Q) using a standard FFT algorithm.

Composition Toolbox

The sample composition must be set before the structure factor, S(Q), can be calculated. The sample density (in atoms per cubic angstroms) should also be set here. If the density is to be refined, this is used as the initial value passed to the solver.

Data Options

Spurious peaks or oscillations (e.g. from a slightly mislocated beam stop) in the low-Q region can be removed by setting a Q-min cut-off.

At high Q-values experimental data often becomes increasingly noisy because the relative contribution of coherent scattering to the experimental signal decreases. This increasingly noisy signal can lead to anomalous oscillations near the first peak in D(r). It can therefore be beneficial to truncate the data at high-Q. However truncation can cause spurious peaks in D(r) as a result of the Fourier transform. The positions of these peaks are a function of Q-max, so the use of different values should be investigated. Discussion on the effect of Q-max can be found in ref. [1] and [5].

The option to smooth the data will apply a Savitzky-Golay filter to the data. Options to change the length of the filter window and the order of the polynomial used to fit samples can be found in the Additional Preferences dialog, accessible from the Tools menu.

LiquidDiffract provides the option to use either Ashcroft-Langreth [6] or Faber-Ziman [7] formalisms of the structure factor. See Keen et al., 2001 [8] for discussions of differences in structure factor formalisms, or the LiquidDiffract source code for specific implementations.

In both formalisms the total molecular structure factor, S(Q), is converted to normalised units using the method of Krogh-Moe [9] and Norman [10].

Applying a modification function to S(Q) before FFT can help suppress truncation ripples and can correct a gradient in the high-Q region. Two functions are currently implemented:

Lorch [13]:

M\left(Q\right)=\frac{\sin\left(\tfrac{\pi Q}{Q_{\rm{max}}}\right)}{\left(\tfrac{\pi Q}{Q_{\rm{max}}}\right)}

Cosine Window (Drewitt et al.) [14]:

M\left(Q\right) = \begin{cases}
1 & if ~~ Q \lt Q_{\rm{window-start}}\\
0.5\left[1+\cos\left(\frac{x\pi}{N-1}\right)\right] & if ~~ Q_{\rm{window-start}} \lt Q\leq Q_{\rm{max}}\\
0 & if ~~ Q \gt Q_{\rm{max}}\end{cases}

where N is width of the window function
and x is an integer with values from 0 : (N-1) across the window

After calculating the structure factor the final tab can be

LiquidDiffract

Install / Use

README