farfield simulation matlab

Farfield simulation

simul_farfield is a Matlab function which simulates 3DXRD diffraction patterns of polycrystalline materials for the “far-field” case, e.g. there is no spatial information in the images. The geometry is idealized as follows: a horizontal monochromatic beam of no divergence/ energy-spread; data acquisition while rotating sample around omega-axis perpendicular to the beam in equidistant steps; detector perpendicular (can be tilted) to the beam in a fixed distance to the centre-of-rotation; detector partly ideal (but finite) e.g. no spatial distortion, but a point-spread function can be applied. Coordinate systems as defined in H.F. Poulsen.[1]
Mono-phase material with N grains; fully illuminated at all times. The space group, lattice parameters and atom positions in unit cell are specified in an “unit-cell input file”. The maximum value for which to generate reflections ![2] are given in the main input file. The orientations are either generated randomly or input by the user. Volumes are attributed to the grains according to a scale-independent volume-distribution (by default - log-normal), specified by user and a global scale parameter (the latter proportional to the flux of the incoming beam).
The integrated intensity of the generated diffraction spots can be based on the squared structure factors or simply a constant value. The reflections can be subjected to include Lorentz and polarization factors as defined in the input file. As an option background counts and Poisson noise can be simulated. The latter using the DIPimage matlab toolbox.
The reflection profiles can be simulated in a number of ways.

• As spikes
• Gaussian shape, 2D Gaussian on the detector and 1D Gaussian for the rocking curve
• Profile according to a user defined crystal orientation spread

The potential use is twofold:

• To simulate 3DXRD diffraction patterns for test of indexing, overlap and integration routines
• To simulate patterns for a specific material to estimate the degree of spot overlap, and thereby feasibility, before an actual experiment is performed. This implies some statistics on the images – to be handled by a separate module.

Installation

The source code can be downloaded from fable.sourceforge.net as a zip file or a tarball.
Unpack the distributio using either

unzip simul_farfield-1.4.6.zip

or

tar xvzf simul_farfield-1.4.6.tar.gz

depending on the file format you downloaded.
You can also make a check out of the development version from the subversion repository.

svn checkout https://fable.svn.sourceforge.net/svnroot/fable/simulation/simul_farfield simul_farfield

In MATLAB add the simul_farfield directory to the path

File -> Set Path... -> Add Folder... -> browse to find the simul_farfield folder

DIPlib and the DIPimage matlab toolbox have to be installed if noise on the frames is to be simulated. For non-commercial use the program can be downloaded here.
Upon installation of DIP_lib_ the file load_diplib.m has to be edited. In MATLAB
edit load_diplib.m
to match your your installation of DIP_lib_. The file is made such that the same file can be used both under Linux and Windows.

Example of load_diplib.m

if strcmp(os,'PCWIN') == 1
    diproot ='C:\Program Files\diplib'
    addpath([diproot,'\dipimage'],[diproot,'\dipimage\diplib'],'-begin')
    dip_initialise
else
    diproot ='/usr/local/dip/toolbox'
    addpath([diproot,'/dipimage'],[diproot,'/diplib'],'-begin')
    dip_initialise
end

Running simul_farfield

[graininfo A] = simul_farfield(’input_main’,’input_structure’)

Non-interactive simul_farfield

Create a shell script as follows and edit it suitably.

1 2 3 4 5 6 7

#!/bin/tcsh unsetenv DISPLAY matlab >&! my_log_file.log << EOF [graininfo A] = simul_farfield('input_2CEU','start_2_2_5') exit EOF

Input

The input is made as either one or two matlab script files. It is generally recommended to use two files. Separating the parameters describing the experimental setup (input_main.m) and the structural parameters (input_structure.m). This is merely a suggestion for a better overview of the input.
The structure of the input files:

• input_main.m
• input_structure.m

Some example input files are found in input_examples of the subversion repository. The input file (called input_structure.m here) can be build using one of the python scripts described below from a cif file (often the way crystallographic data is stored for organic and metal-organic compound) of from a pdb file (file format most often used for storing the data from macromolecular structures).

Output

The function returns two arrays graininfo and A.
graininfo contains information about the simulated grains. graininfo automatically saved as graininfo.mat

Column       Value
1:           grain number
2:           grain size (μ)
3:           grain volume (μ³)
4:           Euler angle; φ1 (degrees)
5:           Euler angle; Φ (degrees)
6:           Euler angle; φ2 (degrees)
7-13:        Orientation matrix elements in the order:
             U(1,1) U(1,2) U(1,3) U(2,1) U(2,2) U(2,3) U(3,1) U(3,2) U(3,3)

A contains information about all simulated reflections for all grains. A is automatically saved as A.mat.

Column       Value
1:           Reflection number
2:           Number of grain it belongs to
3:           Number of reflection in the reflection set of the grains
4:           h
5:           k
6:           l
7:           Structure factor squared - |F|²
8:           Euler angle; φ1 (degrees)
9:           Euler angle; Φ (degrees)
10:          Euler angle; φ2 (degrees)
11:          Gw(1)
12:          Gw(2)
13:          Gw(3)
14:          ω
15:          2θ
16:          η
17:          Detector position y
18:          Detector position z
19:          Lorentz factor
20:          Polarization factor
21:          Integrated intensity
22:          sin(θ)/λ

Definitions for all the parameters can be found in ![1]
Diffraction images if requested in the input_main.m file. The file names are as fileprefix####.tif i.e. frames are saved as tiff files. The frames are stored in the directory specified in the input file. Processing tif images in ImageD11 requires that o11=o22=-1 and o12=o21=0.
Scattering vectors (g-vectors) are now (from version 1.4.3) also written to a file. The format of g-vector file is that of ImageD11. This enables one to run e.g. GrainSpotter without doing peaksearch first.

#auxprograms?Auxiliary programs

cif2matlab.py is a python script to transform the crystallographic structure in cif format to the matlab structure read by simul_farfield. The python script uses PyCifRW module to read the cif file.

cif2matlab.py  <file.cif> <datablockname>

a structure file called input_datablockname.m will be written. In a cif file more than one structure and furthermore there can be some extra information. Each of these parts (structures) are started by the code '''data_<datablockname>'''. Hence datablockname is the part after data_ in the cif file, e.g. tft if a line like this, data_tft, is found.
pdb2matlab.py is a python script to transform the crystallographic structure in PDB format to the matlab structure read by simul_farfield.

pdb2matlab.py  <file.pdb>

The output file is named input_'file'.pdb.

Analyse spot overlap fraction in data set

shell_overlap.m is a MATLAB function to estimate the degree of overlapping reflections in equal volume resolution shells. The function can be called like this:

 overlap_table = shell_overlaps(A,dy,dz,dw)

Input
A is the matrix output by simul_farfield. It is the list of all simulated reflections and their detector positions etc. The criteria for considering two reflections as overlapping is defined by three parameters dy, dz and dw. If the center of two reflections are less than dy, dz, dw apart they are considered to be overlapping. dy is the distance in detector y (pixels), dz is the distance in detector z (pixels), and dw is the distance in the along omega (degrees). (dy,dz,dw) could be something like (11,11,0.4) dependent on the crystal mosaicity and the detector point-spread.

Output
The output is a table of overlap ratios as a function of resolution. The overlaps have been divided into equally volume sized resolution shells. The limits of each resolution shell is given as both sin(theta)/lambda [Å]^-1 (column 1) and d-spacing [Å] (column 2). Column 3 is the number of reflections in the resolution shell. Column 4 contains number of overlapping reflections and 5 the percentage of reflections overlapping. The final row shows the numbers for the full reciprocal volume.

History

simul_farfield is a generalization of the reflection Matlab simulator for cubic space groups by H.F. Poulsen. The original code is found on the SVN online
The algorithm to determine the omega value(s) at which the reflections are in diffraction condition was originally written by Søren Schmidt.

License

Copyright (c) 2006, Henning Osholm Sørensen, Risø National Laboratory, DK-4000 Roskilde, Denmark
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

• Redistributions of source code must retain the above copyright notice, this list of con-ditions and the following disclaimer.
• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
• Neither the name of the Risø National Laboratory nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

This software is provided by the copyright holders and contributors "AS IS" and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. In no event shall the copyright owner or contributors be liable for any direct, indirect incidential, special, exemplary, or consequential damages (including but not limited to, procurement of substitute goods or services, loss of use, data or profits or business interruption) however caused and on any theory of liability, whether in contract, strict liability or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such.

References

1. Poulsen, H.F., Three-dimensional X-ray diffraction microscopy. Mapping polycrystals and their dynamics. (Springer Tracts in Modern Physics, v. 205) (Springer, Berlin, 2004)
2. Le Page, Y and Gabe, E.J., J. Appl. Cryst. (1979) 12, 454-466.