EMsampleRFZ
Several of the programs in the EMsoft package require a list of orientations that represents a uniform sampling of orientation space. A special program is provided to generate such uniform samples: EMsampleRFZ. As usual, this program needs a name list file as input, and we generate the template file as follows:
EMsampleRFZ -tThe letters "RFZ" in the program name stand for "Rodrigues Fundamental Zone". This is the volume in Rodrigues space that contains all the unique orientations for a given crystallographic symmetry.
Before we delve into the name list entries, let us briefly review the different modes in which the program can be operated:
- a uniform sampling of a Rodrigues fundamental zone (FZ);
- a uniform sampling of orientations at less than a given misorientation from a given orientation;
- uniform sampling based on the Marsaglia algorithm for random unit quaternion generation;
- uniform sampling based on the Mersenne twister uniform random number generator;
- super-Fibonacci sampling;
- conical sampling [experimental];
- uniform fiber texture sampling [experimental].
Sampling methods 1 and 2 are based on the cubochoric rotation representation, which starts with a cubical grid inside the cubochoric cube. This cube represents an equal-volume mapping of the quaternion Northern hemisphere (i.e., all 3D rotations with positive scalar quaternion component). For sampling mode 1, the program creates a uniform grid of cubochoric vectors, transforms each vector to the Rodrigues representation and determines whether or not the point lies inside the FZ for the point group symmetry set by the user. The program then returns an array of Euler angle triplets (Bunge zxz convention) for use in other programs. The sampling grid can be offset from the center of the cube, in which case the identity orientation will not be part of the sample.
For sampling mode 2, the program samples a centered cube inside the cubochoric cube and converts those points to points inside a quadratic surface (prolate spheroid, spheroidal paraboloid, or double-sheet hyperboloid, depending on the parameter choices) in Rodrigues Space; all generated points will have at most the given misorientation with respect to a user defined reference point.
Detailed information on the cubochoric rotation representation can be found in the following paper: D. Rosca, A. Morawiec, and M. De Graef. "A new method of constructing a grid in the space of 3D rotations and its applications to texture analysis," Modeling and Simulations in Materials Science and Engineering 22, 075013 (2014).
Details on the misorientation sampling approach can be found in the following paper: S. Singh and M. De Graef, "Orientation sampling for dictionary-based diffraction pattern indexing methods," MSMSE 24, 085013 (2016).
Sampling mode 5 is based on a paper by M. Alexa entitled Super-Fibonacci Spirals: Fast, Low-Discrepancy Sampling of SO(3). This approach employs uniform sampling inside a cylinder which is then mapped onto SO(3) using an equal-volume mapping. This option was added on 12/21/22 and is still being evaluated in terms of its usefulness for dictionary indexing. There is an example at the end of this document.
Crystallographic point groups are identified by an integer from 1 to 32 according to the International Tables for Crystallography (Volume A). The valid numbers, along with the corresponding Hermann-Mauguin point group symbols, are listed here, along with the point group symbol between double quotation marks, the corresponding rotation group and its order M (in bold face):
| ID/Symbol | ID/Symbol | ID/Symbol | ID/Symbol |
|---|---|---|---|
| 1/"1"/1(1) | 2/"-1"/1(1) | 3/"2"/2(2) | 4/"m"/2(2) |
| 5/"2/m"/2(2) | 6/"222" /222(4) | 7/"mm2" /222(4) | 8/"mmm" /222(4) |
| 9/"4" /4(4) | 10/"-4"/4(4) | 11/"4/m"/4(4) | 12/"422"/422(8) |
| 13/"4mm"/422(8) | 14/"-42m"/422(8) | 15/"4/mmm"/422(8) | 16/"3"/3(3) |
| 17/"-3"/3(3) | 18/"32"/32(6) | 19/ "3m" /32(6) | 20/"-3m"/32(6) |
| 21/"6"/6(6) | 22/"-6" /6(6) | 23/"6/m"/6(6) | 24/"622"/622(12) |
| 25/"6mm"/622(12) | 26/"-6m2"/622(12) | 27/"6/mmm"/622(12) | 28/"23"/23(12) |
| 29/"m3"/23(12) | 30/"432"/432(24) | 31/"-43m"/432(24) | 32/"m-3m"/432(24) |
The cubochoric space is a cube with edge length pi^(2/3) and origin (the identity rotation) at the center of the cube. The number of sampling points entered by the user represents the number of grid points along a semi-edge of the cube. In other words, if the user requests N=50 sampling points, and the origin is part of the grid (see next item), then there will be 2N+1 actual sampling points along each cube edge. The total number of sampling points in the grid will then be (2N+1)^3. For point groups #1 and #2, in the absence of any rotational symmetry, the Rodrigues FZ will correspond to the full cubochoric grid, with (2N+1)^3 grid points. For any other point group, the Rodrigues FZ will correspond to a portion of the cubochoric grid, and the number of points will be approximately given by (2N+1)^3 /M, where M is the order of the rotation group corresponding to the point group. In the table above, the rotation group and its order are indicated in bold face.
##Grid offset switch## For sampling mode 1, the user has the option to offset the cubochoric grid from the origin by half a grid unit. In that case, the grid will have a maximum of 8N^3 grid points, and the identity rotation will not be part of the sample. The total number of points inside the Rodrigues FZ will then be approximately 8N^3 /M.
For sampling mode 2, the user must provide a reference orientation in the form of an Euler angle triplet (Bunge convention); this orientation will be used as the reference orientation around which the misorientation sampling will be computed. The output of both sampling modes will be in the orientation representation selected by the user. Multiple orientation output files can be generated in one program execution.
The default entries in the template name list file are as follows:
&RFZlist
! template file for the EMsampleRFZ program
!
! sampling mode; select from the following options
! 'RFZ' standard Rodrigues FZ;
! 'MIS' misorientation ball sampling;
! 'MAR' for Marsaglia random unit quaternion generation;
! 'UNI' for linear uniform random quaternions;
! 'SFS' for Super-Fibonacci sampling;
! 'CON' conical sampling; [experimental]
! 'FIB' for uniform fiber texture sampling. [experimental]
samplemode = 'RFZ'
!=================
! parameters for all sampling modes
!=================
! coverage of SO(3)
! 'single': quaternions q and -1 are treated individually
! 'double': quaternions with negative scalar part are negated
SO3cover = 'single'
! active quaternion that rotates the entire fundamental zone before sampling
qFZ = 1.D0 0.D0 0.D0 0.D0,
! or an active axis-angle pair for the FZ rotation before sampling ( rotation axis, angle in degrees )
! [the rotation axis need not be normalized]
axFZ = 0.D0 0.D0 1.D0 0.D0,
! point group number; please use 0 if no symmetry reduction should be applied
!#1: '1', #2: '-1', #3: '2', #4: 'm', #5: '2/m', #6: '222', #7: 'mm2', #8: 'mmm'
!#9: '4', #10: '-4', #11: '4/m', #12: '422', #13: '4mm', #14: '-42m', #15: '4/mmm', #16: '3'
!#17: '-3', #18: '32', #19: '3m', #20: '-3m', #21: '6', #22: '-6', #23: '6/m', #24: '622'
!#25: '6mm', #26: '-6m2', #27: '6/mmm', #28: '23', #29: 'm3', #30: '432', #31: '-43m', #32: 'm-3m'
pgnum = 32,
! euler angle output file name
euoutname = 'undefined',
! cubochoric output file name
cuoutname = 'undefined',
! homochoric output file name
hooutname = 'undefined',
! Rodrigues output file name
rooutname = 'undefined',
! quaternion output file name
quoutname = 'undefined',
! orientation matrix output file name
omoutname = 'undefined',
! axis angle pair output file name
axoutname = 'undefined',
! stereographic output file name
stoutname = 'undefined',
! rotation vector output file name
rvoutname = 'undefined',
!
! if a zone plate representation of the orientation set is needed,
! change this parameter to a tiff filename (relative to EMdatapathname)
zoneplate = 'undefined',
!=================
! parameters for RFZ mode
!=================
! number of sampling points along cube semi-edge
nsteps = 100,
! grid type: 0 contains origin, 1 is has origin at center of grid box
gridtype = 0,
!=================
! parameters for FIB mode
!=================
! crystal structure file name (used for FIB samplemode only)
xtalname = 'undefined'
!=================
! parameters for MIS mode
!=================
! maximum misorientation [degrees], for 'MIS' samplemode only
maxmisor = 5.D0,
! Rodrigues vector (n,tan(omega/2)) for center of misorientation ball, for 'MIS' samplemode only
rodrigues = 0.D0, 0.D0, 0.D0, 0.D0,
!=================
! parameters for CON mode
!=================
! cone axis for 'CON' samplemode
conevector = 0.D0, 0.D0, 1.D0,
! cone semi-angle (in degrees)
semiconeangle = 2.D0,
!=================
! parameters for SFS, MAR, and UNI modes
!=================
! set the number of samples to be generated
norientations = 100000,
/For mode 1 sampling, set the samplemode to RFZ, set the xtalname to the correct crystal structure file name, define the number N of steps along the semi-edge of the cubochoric cube (variable nsteps), enter the grid offset parameter (0 represents no offset, 1 shifts the whole grid by half a grid box), and then set all of the filenames corresponding to the orientation representations that you desire.
There is also an option to rotate the entire Fundamental Zone before sampling it. This can be done specifying one of the variable qFZ or axFZ. With qFZ, an active quaternion can be defined that rotates the entire FZ prior to sampling; axFZ does the same but in the form of an axis-angle pair. If both are present only the axis-angle pair rotation will be applied.
Let us assume that you need a uniform orientation sampling in quaternion form for Nickel (cubic symmetry), and you want to have about 1.5° average step size in all directions in orientation space; we call this angle theta. The number of sampling points N that will get you approximately this average step size is then given by nint(131.9705 / (theta-0.0373)), where theta is entered in degrees and nint is the nearest integer. For theta=1.5°, we find N = 90. So, we generate the following name list (all unnecessary lines have been removed):
&RFZlist
samplemode = 'RFZ'
pgnum = 32,
nsteps = 90,
gridtype = 0,
quoutname = 'quats.txt',
/Running the program for this name list file will generate a text file with 243129 quaternions; the file will look like this:
qu
243129
0.856244 -0.347427 -0.347427 -0.159487
0.856244 -0.349317 -0.349317 -0.151003
0.856244 -0.351107 -0.351107 -0.142456
... (many lines deleted)
0.856244 0.349317 0.349317 0.151003
0.856244 0.347427 0.347427 0.159487The first line indicates the orientation representation (qu for quaternions), the next line has the total number of quaternions in the sampling set, and then each line has a single quaternion, with the scalar part in the first position. This type of text file can be used by many other programs in the EMsoft package, for instance EMEBSD and the dictionary indexing programs.
In the example, we assume that the user requires a uniform sampling inside a ball with a certain radius (say 5°) around a given orientation, represented as a Rodrigues vector. We pick the following orientation: 45°@[110]. The name list file then looks as follows:
&RFZlist
samplemode = 'MIS'
maxmisor = 5.D0,
rodrigues = 0.70710677D0 0.70710677D0 0.D0 0.41421357D0,
pgnum = 32,
nsteps = 10,
gridtype = 0,
rooutname = 'rods.txt',
/Note that the first three components of the Rodrigues vector must form a unit vector, and the fourth component is the length of the vector. Note also that the nsteps parameter represents the number of points along the semi-edge of the 5° cube, so a value of 90 here would generate more than 5 million samples, since all of them fall inside the RFZ. This name list file generates the following output file in Rodrigues representation:
ro
9261
0.689428 0.722192 0.055931 0.457444
0.691078 0.720976 0.051038 0.459021
...In this final example we use the super-Fibonacci sampling approach to generate a collection of orientations with low dispersion (see paper cited above). The essential portion of the namelist file is as follows:
&RFZlist
samplemode = 'SFS'
SFSn = 400000
pgnum = 1,
quoutname = 'relative path/quats.txt',This namelist file instructs the program to generate a target total of 400,000 quaternions using the Super-Fibonacci sampling technique. For point group 1 there is no fundamental zone, so that the orientations will cover the entire SO(3). Whether or not this sampling method is better than the normal cubochoric sampling in the context of dictionary indexing remains to be seen. Execution of the program with the above namelist file results in a text file starting with the following lines:
qu
400000
0.001042044 -0.000405147 0.888141318 -0.459569091
0.000000000 0.001736613 -0.137825152 0.990455053
0.000000000 -0.002400362 -0.728926130 -0.684588150
0.002528135 0.001535751 0.979867261 -0.199628154
0.000000000 0.000652350 -0.403003566 0.915198175
0.002194863 -0.002988742 -0.514324664 -0.857587541
0.000435327 0.004007554 0.997139229 0.075479187
0.000000000 -0.002858373 -0.637557784 0.770397236
0.004608788 -0.000095253 -0.260645037 -0.965423697
0.000000000 0.003365504 0.938651233 0.344851468
...When the ppoint group number is set to a value different from 1, the total number of orientations generated by this approach may be slightly different from the target number. For instance, for pgnum=32, the algorithm generates 400,005 orientations. This discrepancy is due to rounding issues near fundamental zone facets.
The paper on the Super-Fibonacci sampling algorithm describes a method to display a range of orientations in a 2-D "zone plate" based on a sectioning of the Clifford Torus. The EMsampleRFZ program has an option to generate a tiff file with the zone plate containing information for the specific set of sampled orientations; this will work regardless of the sampling mode. Details can be found in the paper. This is an experimental feature; it is not clear whether or not this is a useful option to have. To use this option, simply set the zoneplate parameter to a path to a .tiff file (i.e., replace "undefined" by the desired filename).
The zone plate is defined as a square with dimensions [-pi,pi] along both horizontal and vertical directions. Each orientation quaternion is first projected onto the Clifford torus, which is defined by having the sum of the squares of the first two quaternion components be equal to 1/2, and the same for the sum of the last two components; in other words, the quaternion components are pairwise renormalized to 1/2. Then each pair is converted via the arc-tangent function to a point with coordinates (atan2(q1,q0), atan2(q3,q2)) in the zone plate (qi are the quaternion components on the Clifford torus). At that location, a narrow 2D Gaussian is added to the zone plate, and this process is repeated for all quaternions. The amplitude of the Gaussian is modulated by the zoe plate function where
is the geodesic distance between the quaternion and a reference quaternion
(with
) on the Clifford torus. This function modulates the intensities and makes it easier to see uneven distributions of orientations.
The figure below shows the zone plates for four different samplings:
- top left: super-Fibonacci sampling of the entire
quaternion sphere; q and -q are treated independently and there is no symmetry applied;
- top right: Marsaglia sampling;
- bottom left: uniform sampling using the Mersenne twister;
- bottom right: cubochoric sampling without symmetry, but with a reduction of -q to q; this results in the absence of intensity on both sides of the zone plate. Note that this was carried out with gridtype=1.
Note that the super-Fibonacci sampling produces the most regular zone plate and is therefore the most regular orientation sampling approach. Marsaglia sampling shows a non-uniformity in the intensities with some vertical banding, whereas uniform Mersenne twister sampling shows a 2D grid of non-uniformity. The cubochoric sampling approach is close to the perfect super-Fibonacci result but has some weak highly localized non-uniformities that show up as faint horizontal streaks.
When crystal symmetry is applied, RFZ sampling shows intensity in a sub-region of the zone plate. For point group 4/m, the zone plate for cubochoric sampling is shown on the left below. Note that the intensities are non-uniform in this case due to the fact that a crystallographic sub-space of SO(3) is being sampled. On the right, RFZ sampling for point group m -3 m is shown. The bottom row shows the same point group zone plates but this time for super-Fibonacci sampling. These plots suggest that super-Fibonacci sampling should be preferred over the cubochoric sampling that has been used for dictionary indexing so far.
The final figure below shows the zone plates for the 11 rotational point groups using the super-Fibonacci sampling method.
