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.
Reference: Søren Schmidt, GrainSpotter: a fast and robust polycrystalline indexing algorithm, J. Appl. Cryst. (2014). 47, 276-284.
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
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. :
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.
- 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.
- Move log view to and editor
- 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.