grainspotter

GrainSpotter (v. 0.90)

Grainspotter is a program for spotting (indexing) grains based on a set of G-vectors.
It is generally applicable to monophase polycrystalline materials. (For multiphase materials first separate diffraction spots using FABLE module transformer - part of ImageD11). It was developed for far field detectors where the pixel size is almost as large as the sample size, but can also in certain cases be used for nearfield detectors. Input is the G-vector file generated by transformer Output is a grains file comprising a list of grains; their orientations and center-of-mass positions and information about which peaks are associated with which grain.

Grainspotter exists as a standalone C program and integrated as a GUI in the FABLE GUI workbench. The functionality is the same and this note covers both versions.

Author: Søren Schmidt, NEXMAP, Department of Physics, Technical University of Denmark, Denmark

Reference: Søren Schmidt, GrainSpotter: a fast and robust polycrystalline indexing algorithm, J. Appl. Cryst. (2014). 47, 276-284. (scripts.iucr.org)

1. Installation

If you have installed the FABLE GUI workbench, you are ready to use the GUI version.

If you are interested in the stand-alone version you can check out the development version via SVN.

svn checkout https://fable.svn.sourceforge.net/svnroot/fable/GrainSpotter

Generally an executable (GrainSpotter.0.90) on a Linux/Unix system can be made as follows

cd GrainSpotter/trunk
make

The executable can now be copied to a directory in your path e.g. /usr/local/bin.

The program is executed in shell as follows

:~> GrainSpotter.0.90 myinputfile.ini

or on Windows open and command shell (click START -> run... and type cmd in the entry)
go to the directory where you stored the .ini file and type

2. User Guide

needs two types of input: g-vector files and an initialization file, typically named *.ini.
An example of an ini file can be found in the GrainSpotter?/trunk directory.

2. 1 Initialization file (.ini file)

Below is an example of an input file. Characters after exclamation marks (!) are not read by GrainSpotter

spacegroup 225                ! spacegroup [space group nr]
etarange 0 360                ! etarange [min max]
dsrange 0.0 0.075             ! dsrange [min max], reciprocal d-spacing range, multiple ranges can be specified
!tthrange 0 30                ! tthrange [min max], multiple ranges can be specified
domega 0.5                    ! domega [stepsize] in omega, degrees
omegarange -45 45             ! omegarange [min max] degrees, multiple ranges can be specified
filespecs data.gve grains.log ! filespecs [gvecsfile grainsfile]
cuts 5 0.6 0.8                ! cuts [min_measuments min_completeness min_uniqueness]
eulerstep 6                   ! eulerstep [stepsize] : angle step size in Euler space
uncertainties 0.1 0.2 0.5     ! uncertainties [sigma_tth sigma_eta sigma_omega] in degrees
nsigmas 2                     ! nsigmas [Nsig] : maximal deviation in sigmas
!Nhkls_in_indexing 15         ! Nhkls_in_indexing [Nfamilies] : use first Nfamilies in indexing
!random 10000                 ! random sampling of orientation space trying 10000 sample points
positionfit

Below is a guide to the definition and use of the keywords in the ini file

• spacegroup number

The space group id (integer between 1 and 230). This is mainly used to handle ensure that the determined orientation falls into the fundamental zone – a unique part of orientation space. Hence the same solution will always have the same U matrix, not one of the other possible transformations allowed by the space group symmetry. This is mainly a concern in materials science, less so for structure solution and refinement., A list of space groups is given below. If space group is not known, program will run with any input.

• etarange minimum maximum [degrees]

The active interval in the eta angle range (values between 0 and 360 degrees can be used ). OBS you can put in more than one interval.

• tthrange minimum maximum [degrees]

The radial active interval defined as a twotheta range (maximum > minimum ³0 ). Instead of tthrange the radial scattering range can alternative be defined by the dsrange (see dsrange keyword below). OBS you can put in more than one interval.

• dsrange minimum maximum [1/Å]

The radial active interval as a d range, d = 2 sin(theta)/lambda (floating point values and maximum > minimum ³0 ). Analogous to the restricting the radial scattering area by the tthrange documented above. OBS you can put in more than one interval.

• omegarange minimum maximum [degrees]

The active interval in the omega range. I all data are to be used these should match start and end omega positions of the experiment (180 ³ maximum > minimum ³ -180). OBS more than one range can be provided.

• domega omega_stepsize [degrees]

The omega step size (the rocking angle for each acquisition) used in the data collection.

• filespecs g-vector_filename log_file_name

Path and filenames of the input g-vector file (from ImageD11) and the output grains file containing the crystallographic orientations, information about fitting reflections etc.

• cuts min_no_measuments min_completeness min_uniqueness

Minimum requirements for accepting an initial grain solution:
- Minimum number of g-vectors assigned to the grain, min_no_measurements (integer value > 3),
- Minimum fraction of expected reflections assigned (#assigned reflections/#theoretical reflections) to the grain, min_completeness (floating number between 0 and 1).
- min uniqueness is OBSOLETE (enter any number)

• eulerstep orientation_angle_stepsize [degrees]

The number defines the size of the volume around the random orientation in which a possible match can be found. By making eulerstep small the possible solutions for each step are reduced, which makes it faster. However, then you might also need more random steps to find all grains. A sensible value for eulerstep is around 3-6 degrees.

• uncertainties sigma_twotheta sigma_eta sigma_omega [degrees]

Give YOUR estimation on the uncertainties (FWHM) in degrees on eta, omega and twotheta. Typically sigma_twotheta is 0.05-0.1 deg, sigma_eta is 0.1-0.2 deg while sigma_omega is equal to domega. Multiplied by nsigmas (see below) these numbers "decide" whether a theoretical gvector match an observed,. Often it is required to vary these parameters a bit to optimise GrainSpotter performance.

• nsigmas 2 ! maximal deviation in sigmas

Determines the maximal deviation allowed for Grainspotter to (initially) accept a peak as belonging to a certain grain. Generally, the rule of acceptance is |d_quantity| < nsigmas * sig_quantity. Experience shows that a number of 2 is good.

• Nhkls_in_indexing 10 ! use first Nhkls_in_indexing hklfamilies in indexing

Uses the first Nhkls_in_indexing hkl families for the first part of the analysis. Afterward the search for additional gvectors belonging to the grain is done on the remaining rings.

• random 100000

· The number following random trial samplings in orientation space. Typically the number is between 10,000 and 100,000. The run time is proportional to this number. One may optimize the value by initially setting it very large and observing on line when Grainspotter stops generating new grains. :
·

• positionfit

This flag is toggled off by commenting the line out. When the flag is set, the condition for identifying a grain will include a test of whether all refelctions appear to emerge from the same spatial position. The center-of-mass position will be part of the optimisation process for a given grain and it will be written to the output grains file.

3. Outputfile: the grains file

For each grain found the following is listed:

Grain number
#expected gvectors #measured gvectors #measured once #measured more than once
mean_IA position_x position_y position_z pos_chisq
 U11 U12 U13
U21 U22 U23
U31 U32 U33

UBI11 UBI12 UBI13
UBI21 UBI22 UBI23
UBI31 UBI32 UBI33

r1 r2 r3

phi1 phi phi2

q0 qx qy qz

#  gvector_id peak_id  h k l  h_pred k_pred l_pred  dh dk dl  tth_meas tth_pred dtth.....
                                               omega_meas omega_pred domega  eta_meas  eta_pred deta  IA

• U11 ... U33 is the elements of the oriention matrix, U, as defined by Busing-Levy.
• UBI11 ... UBI33 is the elements in the inverted matrix U times B.
• !r1 ... !r3 is the orientation given as a Rodrigues vector
• phi1 Phi phi2 is the orientation given as Euler angles
• q's are the orientation given as a quarternion
• IA is the internal angle, i.e. the angle between the theoretical lattice vector and the experimental in degrees
• mean_IA is then the mean of all IA's of a grain
• position_x, position_y, position_z is the spatial position of the grain in the laboratory coordinate system (in mm)
• pos_chisq is the chi square value between the fitted model scattering vectors and the experimental scattering vectors. For a good fit this value should approach zero.

4. Graphical User Interface

4. 1Required Plug-in

**fable.grainspotter** : Grainspotter GUI core
**fable.framework.navigator** : navigator to select several files (to do)
**fable.framework.toolbox** : fable toolBox with typed Text field (required, format ...) and usefull static functions.

4. 2 View Grainspotter

Grainspotter view represents all parameters found in 'ini' file needed for GrainSpotter.

- Ini fields are required field.
- View can be load with a ini file selected in menu 'File/ini'.
- And a new ini file can be saved with values set in fields from View GrainSpotter.

Constraints on values

//Parameter//                 //Type//    //Constraint//
**SpaceGroup**            integer    0<>230
**Etaspec**                 float    0<=x<=360
**OmegaSpec min**         float    -180<=x<=180
**OmegaSpec max**         float    -180<=x<=180
**OmegaSpec delta**         float    0< x<1
**Gvector**                 file Name    .gve extension
**Log file**                 file name    .log extension
**Cuts min measurement**  integer    x>3
**Cuts min_completeness** float    0<=1
**EulerStep**         float    0<=x<=180
**Uncertanties sigma_tth,**
**sigma_eta, sigma_omega**float    0

After running GrainSpotter, results are stored in log file (file name set in ini file) and results are shown in a new output view.

5. Using the condor cluster

GrainSpotter has been tested using the condor cluster at ESRF CondorESRF and found to work. Some hints are collected on that page.

8. TODO

• Grainspotter :Supply a eta-omega map with deadzones.
• Gui :
• Add UBI in 3d plot view
• Make a "logical link" between log/gve text editors and views to avoid browsing editor, and browsing again to open the same file in a view or a plot: maybe move views to editors for log file table at least?
• 3D plot: add individual colors for the different grains
• 3D plot: color all g-vectors, not anly those matches by Grainspotter
• Add a plot for log file (IA/f(grains), completeness f(grains), gve measured/gve expected f(grains))
• Add save and save as... in menu Grainspotter
• Add a dialog box before launching grainspotter if ini file has been edited instead of saving it with no warning.....
• Activate f1 context help again
• Grains3D tab: after running grainspotter this did not show anything.

After opening log file manually it worked.

1. Move log view to and editor
2. Add an expand all in Treeviewer for the log file view

9. fable 1.0.0

- Fix bug on delta omega with a range 0-360 instead of 0-1
- Rename Menu Grainspotter/Gvectors/"Open 3D plot" to "Open in 3D plot" for log file
- Add a radio button to choose between scan or random search mode
- Parse log file for g-vectors has been fixed (shift +1 for the parsing to get the g-vector id).
- Fix bug concerning buttons save and save as....: in RC8, one pair of buttons was added in the toolbar. now only one pair of buttons is displayed and "linked" with current grainspotter editor.