This section describes the input file format for PolyXSim. This has been taken from the wiki page, refer to (http://fable.wiki.sourceforge.net/PolyXSim+-+input) for the latest version.

Input


The input to PolyXSim is given as an ascii file. The file can be given any name. An example of an input file can be found here.

The input is given by a set of input keywords followed by one or several values dependent on the type of keyword specified. The keywords can be group by their type as seen below.

The syntax is as follows

Followed by an input example:

keyword value                    # some explanation

if the value is a string in should be given in quotation marks 'value'

keyword 'value'                  # string values should en enclosed by quotation marks

if the value is a numeric number the format is free.
E.g.

keyword 10
keyword 10.0
keyword 1e1
keyword 10**1
keyword 20/2.0

anything goes - or almost anything!

Instrumentation

Beam specs

wavelength 24.344         # wavelength in Å
beamflux  1e13            # Beam flux (Ph/s/mm2)
beampol_factor 1.0        # Beam polarisation factor: 1 = fully plane polarised, 0 = unpolarised
beampol_direct 0.0        # Direction of the normal to the plane of the primary beam polarisation
                          # with respect to the sample rotation axis (degrees) e.g. if the omega
                          # rotation axis is parallel to the laboratory z-axis the value is
                          # 0.0 degrees and if along y-axis it is 90.0 degrees

Detector specification e.g. Frelon2K non-binned specs below

Beam center on detector -

dety_center 1023.5               # beamcenter, y in pixel coordinatees
detz_center 1023.5               # beamcenter, z in pixel coordinatees

Detector pixel size -

y_size         0.04677648        # Pixel size y (mm)
z_size         0.04808150        # Pixel size z (mm)

Detector size -

dety_size   2048.0               # detector y size (pixels)
detz_size   2048.0               # detector z size (pixels)

Distance from sample to detector -

distance      55.0               # sample-detector distance (mm)

Detector tilts -

tilt_x 0.0      # detector tilt counterclockwise around laboratory x axis (beam direction) in radians
tilt_y 0.01     # detector tilt counterclockwise around laboratory y axis in radians
tilt_z 0.0      # detector tilt counterclockwise around laboratory z axis (same as omega axis) in radians

OBS: If diffraction images are to be formed it is also possible to simulate detector point spread, background and noise. See below.

Detector orientation -
Two things determine the detector orientation: 1. How it is mounted in the beam line setup and 2. How the device server reads out the image.
To get the image in the "fable" standard orientation a orientation matrix o can be specifed:

o = [o11 o21] [o21 o22]
There are eight possible o matrices for the eight possible orientations.

o11  1               # Frelon2k, Frelon4m detector orientation
o12  0               #
o21  0               #
o22 -1               #

OBS: In principle the choice of matrix does not matter - only if you want to get the images in the same orientation as what you get on a specific setup. Remember the values given here has to be the same if analysing the data in ImageD11.

Omega scan range, step size and speed

Omega scan range -

omega_start  -45.0             # Minimum Omega in range of interest (in deg)
omega_end     45.0             # Maximum Omega in range of interest (in deg)

Omega step size -

omega_step     2.0             # Omega step size (in deg)
omega_speed    1.0             # Collection speed (seconds/deg), just a scaling of the intensities

Omega rotation speed and direction -

omega_speed    1.0             # Collection speed (seconds/deg), just a scaling of the intensities
omega_sign     1               # Sign of omega rotation (cw = +1, ccw = -1)

Wedge angle of omega axis
The angle between the omega rotation axis and the z-laboratory axis in the plane of x and z, i.e. if 0 the rotation axis is perfectly aligned with the z-axis.

wedge          0.023           # wedge of omega rotation axis (in deg)

Crystal/grain parameters

Grain/crystal number in sample to be simulated

no_grains 10       # Number of grains to be simulated if grain specific parameters as orientations etc.
                   # This number needs to match the number of e.g. U_grains_X keywords

Grain orientations

Can be either randomly generated, or specific orientation matrices can be input by the user.

If flag=1 then no_grains random orientations will be generated

gen_U 1                    # Generate orientations

X needs to be integer - its used to make certain that a grain orientation is correctly matched with its position, size etc.

U_grains_1 -0.888246 0.411253 -0.204671 -0.201101 -0.748709 -0.631659 -0.413011 -0.519909 0.747741
U_grains_2 -0.158282 -0.986955 0.029458 -0.929214 0.158978 0.333597 -0.333929 0.025430 -0.942255
.......

Grain positions

Can be either randomly generated or specific positions can be input by the user.

If flag1=1 no_grains random positions will be generated

gen_pos 1 1                   # Generate random positions

The function of gen_pos is dependent on other keywords (or lack of keywords). For generation of a position different from (0,0,0) one of the keywords sample_cyl or sample_xyz should be given in order define the borders of the sample area.

X needs to be integer - its used to make certain that a grain position is correctly matched with its orientation, size etc.

pos_grains_1 0 0 0
pos_grains_2 0.01 -0.05 0.2
.......

Grain strains

Can be either randomly generated, or specific strains can be input by the user. Note that the strain tensor is given in the Cartesian grain coordinate system, which for each grain is related to the overall sample system via the grain specific orienation matrix U.

If flag=1 then no_grains strain tensors with with elements from a normal distribution with the specified mean and spread will be generated

gen_eps 1 0 0.001 0 0            # Generate random diagonal strain tensors

if a multiphase material is simulated using the above keyword the strain for all grain independt of phase will be generated with the same distribution. It is also possible to have different distributions for every phase.

Y being the phase number id

gen_eps_phase_0 1 0 0.001 0 0            # Generate random diagonal strain tensors
gen_eps_phase_1 1 0 0.02 0 0.01
 

The strain tensors can also been specifically input for every grain

X needs to be integer - its used to make certain that the strain tensor of the grain is correctly matched with its position, size etc.

eps_grains_1 0.001 0.0015 -0.005 0 0 0
eps_grains_2 0.001 -0.005 0.002 0.006 -0.005 -0.001
.......

Grain sizes

Again these can either be user supplied or generated by PolyXSim. The grain sizes will be simulated having a log-normal distribution with a specified median grain size and optionally the distribution tails can be cut off. If only one phase is to be simulated or one wishes to use the same grain distribution for all structural phase the following keyword can be used to specific the distribution


OBS - if value median-grain-size-of-distribution is negative the grain size of all grains will be the value of the median.

gen_size 1 0.05 0.01 0.25        # median grain size for log normal distribution,
                                 # min and max cutoffs for the grain size distribution

Different grain size distributions can be used for the different phase (if more than one are present). This is specified as follows

where Y again is the phase number id.
So the input can look like this for two or more phases,

gen_size_phase_0 1 0.05 0.010 0.25     # median grain size for log normal distribution,
                                      # min and max cutoffs for the grain size distribution
 
gen_size_phase_1 1 0.02 0.005 0.05     # median grain size for log normal distribution,
                                      # min and max cutoffs for the grain size distribution
.....
 

Or the grain size of each grain can be specified

size_grains_1 0.04
size_grains_2 0.06
......

Grain phase

The phase of the individual grains can be specified or appointed by PolyXSim. If you want to let the PolyXSim appoint which grain belongs to which phase the following keyword can be used.

So if choosing to randomly appoint the phase a list of phase id's each succeded by the number of grains of the present phase.
An example with three phases with id'd 0,1 and 2:

gen_phase 1 0 10 1 20 2 5 # 10 grains with phase 0, 20 grains having phase 1, and 5 grains with phase 2
 

Naturally the number of grains should match the number of grains specified with keyword no_grains
Alternatively the phase id of each phase can be specified

where X is the grain id number.

Structural parameters


It is possible to simulate both mono- and multiphase polycrystalline samples.

If there is no interest in the actual peak intensities - only the unit cell and space group have to be specified.

and

or


Presently only the standard space groups can be used, i.e. P 21/n is for example not a possibility.

unit_cell_phase_0  8.531200 4.832100 10.125000 90.000000 92.031000 90.000000
sgno_phase_0  4               # space group number
or
sgname_phase_0 'P21'          # remember to put quotation marks around the string
if more phases the next set will then have the keywords unit_cell_phase_1, sgno_phase_1 etc.
 

OBS: If monophase materails are simulated the old keyword (i.e. without _phase_Y ) can still used.

If 'real' intensities are to be calculated the structural parameters can either be supplied as a cif file or a pdb file.

structure_phase_0 'glycine.cif'

Again if a monophase is simulated the old keyword - structure_file - can be used instead.

If a structure file has information about unit cell and/or space group, these parameter will be chosen over parameters introduced with the keywords unit_cell and/or sgno.

File names and formats


Directory to save output from PolyXSim -

If the specified directory does not exist it will be created.

direc 'simulation_glycine'

Name stem -
The base of all out put files

i.e. image files will get the names name-stem_frame0001.edf etc.

stem 'glycine'


There is a number of files which will be made by default. Whether one likes it or not. But the simulated reflections can be out put in different file formats if requested. What can be chosen

  1. '.edf' or '.tif' - presently the two supported diffraction image formats

  2. '.flt' - a peak file of the same format as output by ImageD11 peaksearch and can be loaded in ImageD11_gui

  3. '.gve' - a g-vector file. Where the peaks are transformed into scattering vectors (g-vectors). This file can be used for indexing in either GrainSpotter or ImageD11- index

  4. '.ini' - an input file for indexing with GrainSpotter using the .gve file is written. It will then be possible to try the GrainSpotter indexing program imidiately.

  5. '.ubi' - grain orientations as inv(U*B)

  6. '.par' - the input parameters for PolyXSim written in the par format of ImageD11


The output files are specified as one after the other in the following manner

output '.edf' '.flt' '.gve' '.ubi' '.par'    # We want the full treat
 

Peak intensities


The total peak intensity can be either be a

  1. constant value, or

  2. based on the structure factor of the reflections

The following keyword is used to control this choice

if the value is zero (0) the structure factor squared are used to calculate the intensities. Otherwise the value given will be the total intensity.

In the calculation of the intensity the effects of

  1. the Lorentz factor and/or

  2. the beam polarisation factor

can also be taken into account using

Peak shapes


Currently only three different peak shapes/profiles are available

Depending on the chosen type more parameters can be added after type. Type can be

Below these three types are documented in more detail.

Spike peak

A square 2-by-2 spike peak



peakshape 0 3

Gaussian peaks

Spot with one FWHM in the y and z detector directions (in pixels) and another in ω (degress)



peakshape 1  2  0.2      # Make the Gaussian peak, peak FWHM in pixels, peakwsig FWHM in omega (in deg)

Orientation spread dependent peaks

Use the 'real' orientation spread of the crystal (mosaicity). OBS - This will not smear intensity in the 2theta direction.

peakshape 2          # Make peak spread from orientation distribution function


There is two possibilities of providing/defining an orientation distribution function (ODF)


1. The simplest one is to give to ODF as a isotropic Gaussian mosaic spread

the mosaicity is then given by the keyword:

Optionally a scale of the ODF grid can be given - by default it is given a value of half the anguler size of a pixel having the smallest angular dimension.

odf_type 1
mosaicity 0.2        # The mosaic spread in degrees

If no odf_type or mosaicity the values above will be used by default.

2. The other is to give the ODF as voxelated grid defined in Rodrigues space. The ODF has to read from a file with the format

odf_type 2
odf_file 'my_odf.odf'