PolyXSim is a program which simulates 3DXRD diffraction patterns of polycrystalline (multiphase) materials for the “far-field” case, e.g. with the detector far away from the sample. The potential use is twofold:

• To simulate 3DXRD diffraction patterns for debugging 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.

The geometry is idealized as follows: a horizontal monochromatic beam of no divergence/ energy-spread; data acquisition while rotating sample around one axis (the omega-axis) in equidistant steps; detector perpendicular or tilted relative to the beam in a fixed distance to the centre-of-rotation; detector accounting for spatial distortion, point-spread function and flood field. Coordinate systems as defined Geometry_version_1.0.9.pdf, H.F. Poulsen.[1] and H.O. Sørensen et al. [2]. If you use PolyXSim for your work, please reference H.O. Sørensen et al. (2012)

The 3DXRD diffraction patterns can be simulated for a multi-phase material with any number of grains. The sample geometry can be either cylindrical or box shaped, and it is possible to simulate the resulting diffraction patterns both when assuming that all grains are fully illuminated at all times, and when the beam width is smaller than the sample dimensions. The space groups and lattice parameters for each phase must be given in the input file along with the maximum value of theta for which to generate reflections ![2]. Alternatively the crystallographic information can be read from a crystallographic information file (.cif) or a protein data bank (.pdb) file.

For each grain the centre-of-mass position, orientation, strain tensor and grain size must be specified by the user or randomly generated by the program according to the following scheme:

• Positions can be randomly generated within a specified sample volume (box or cylinder).
• Orientations can be randomly generated assuming no texture of the sample.
• Strain tensors, given in the Cartesian grain coordinate system, can be randomly generated using a normal distribution with a specified mean and spread. Different distributions can be used for the axial and shear components.
• Grain sizes are attributed according to a scale-independent log-normal size-distribution. The user must specify the mean of the distribution, and optionally also the min and max cut-offs. The grains are assumed to be spherical, so the intensity of the reflections corresponding to a specific grain will be proportional to the cube of the grain size as well as to the flux of the incoming beam which can also be specified.

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
• Using an orientation distribution function, presently the same ODF is used for all grains and phases.

A graphical user interface exists for PolyXSim, see PolyXSim - gui. Presently not all functionalities are supported.

To access all functionalities PolyXSim can be run from the command line specifying an input file in which the parameters being used by simulator has been given. The format of the input file is found here. If the file e.g. is called simul.inp the simulation is started as follows

 PolyXSim.py –i simul.inp

PolyXSim makes a new input file (stem.res) if grain specific parameters is generated by the simulator. This input file can be used to redo the simulation with the same grain orientation, strain etc.

The PolyXSim input file format is the same for both the GUI and the command-line versions.

PolyXSim can be downloaded as part of the Fable GUI.
A stand-alone version can be dowloaded and installed following these instructions.

An extensive description of all input parameters and syntax for the PolyXSim input file can be seen here.
Example input file?.
Warning: I you are using Windows wordpad editing the input file the file gets DOS linebreaks. This prevents the file from being loaded properly in the FABLE GUI. We recommend to edit the input files using Notepad++ instead (notepad++ can also change a windows type file to a unix type file).

The program returns the following files:

• stem.gff which is a column file containing the information about the simulated grains (grain file format)

  The columns of the file comprise:
      1: grain id
      2: phase id
      3: grain size (mm)
      4: grain volume (mm³)
    5-7: grain cms position x y z
   8-16: 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)
  17-25: ubi matrix elements in the order:
         UBI(1,1) UBI(1,2) UBI(1,3) UBI(2,1) UBI(2,2) UBI(2,3) UBI(3,1) UBI(3,2) UBI(3,3)
  26-31: strain tensor elements in the order:
         eps(1,1) eps(1,2) eps(1,3) eps(2,2) eps(2,3) eps(3,3)
  

• stem_gr####_set0000.ref reflection file for grain number #### (OBS: In the newest SVN version of PolyXSim - the parameter '.ref' should be provided using the output keyword in order to output the .ref file)

  Column Value 1: Grain number (yyyy) 2: Reflection number for this grain - reflection id 3: Reflection number for all grains - spot id 4: h 5: k 6: l 7: 2θ - 2 theta angle 8: ω - omega angle 9: η - eta angle 10: dety - detector y coordinate 11: detz - detector z coordinate 12: detyd - detector y coordinate spatially distorted using a spline file 13: detzd - detector z coordinate spatially distorted using a spline file 14: g-vector component along x 15: g-vector component along y 16: g-vector component along z 17: Lorentz factor 18: Polarization factor 19: F² - structure factor squared 20: I - Integrated intensity 21: 0 - Reserved for later use

• stem.res resimulation input file, similar to the original input file except all the generated grain parameters are explicitly given.

Optional output files - a number of files can be generated on request by the user (specificed with the output keyword in the input file)

• stem.ubi which contains the inverse of the UB-matrix for each grain in the standard format.
• stem.par (or stem_phase_X.par, X being the phase number if a multiphase material is simulated) is a detector.par (see format) file containing detector and lattice information for use in ImageD11.
• stem.flt filtered peaks file in the same format as given by [peaksearch] but with the true values of dety, detz and omega.
• stem.gve (or stem_phase_X.gve, X being the phase number if a multiphase material is simulated) gvector file. The format of g-vector file is that of ImageD11. This enables one to run e.g. GrainSpotter without doing peaksearch first.
• stem.ini is an input file for GrainSpotter. The simulated data can be indexed directly using this file and the stem.gve file, if generated.
• stem#### diffraction images. Formats: .edf or .tif

NB! If the detector orientation (o11,o12,o21,o22) is not specified in the input file, they are by default set to o11=o22=1, o12=o21=0.
Definitions for all the parameters can be found in the geometry document: [file:Geometry_version_1.0.7.pdf]

PolyXSim is an implementation and further development of simul_farfield.
Simul_farfiel itself was 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.

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.

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. Sørensen H.O., Schmidt S., Wright J.P., Vaughan G.B.M., Techert S., Garman E.F., Oddershede J., Davaasambu J., Paithankar K.S., Gundlach C. Poulsen H.F., Z. Kristallogr. (2012) 227, 63-78. DOI: 10.1524/zkri.2012.1438
3. Le Page, Y and Gabe, E.J., J. Appl. Cryst. (1979) 12, 454-466.