EMCliffordTorus

Clifford Torus Simulations

On this page, we cover the EMCliffordTorus program. The underlying theory for this algorithm can be found in two papers:

• M. De Graef, "Applications of the Clifford Torus to Materials Textures", Journal of Applied Crystallography, 57, 638-648 (2024) DOI
• C. Lafond and M. De Graef. "Applications of the Clifford Torus Texture Representation to Disorientations in Single and Multi-Phase Materials". Materials Characterization 224:114982 (2025) DOI

In essence, this program takes a set of 3D orientations, converts them to unit quaternions on the quaternion sphere $\mathbb{S}^3$, maps them onto the Clifford Torus and from there, generates three orthogonal projections onto square torus maps. These three maps are then combined into an RGB color image that is a visual representation of the set of orientations, i.e., of the texture of the material. When combined with the EMsampleRFZ program, one can, for instance, generate a training data set for a spherical equivariant CNN that can take an experimental RGB image and determine what the texture components are.

Simulation Parameters

To set up the simulation parameters, go to the folder where you wish to keep the data and type

EMCliffordTorus -t

Rename the resulting template file to whatever name you prefer to use, and make sure to use the extension .nml. The name list file has the following structure:

 &CliffordTorus
! 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'
! additional point groups (note that not all EMsoftOO functionality may be available for these groups)
!#33: '532', #34: ' 822', #35:  '1022', #36:'1222', #37: '312', #38:  '31m', #39:  '-31m', #40: '-4m2'
!#41:'-62m'
 pgnum = 32,
! the angle file, case 1: a simple text file (*.txt or *.wxt) with the following format
! ##      ! two characters denoting the representation (eu, ro, ho, cu, ax, qu)
! n       ! number of entries in file
! ...     ! one line per entry, components separated by spaces
!
! case 2: either an .ang file (EDAX/TSL) or a .ctf file (Oxford); the file extension 
! must be .ang or .ctf!
 anglefile = 'undefined' 'undefined' 'undefined' 'undefined' 'undefined',
! reduce orientations to RFZ (1) or display all equivalent orientations (0)
 reducetoRFZ = 1,
! overlay a line drawing of the Rodrigues FZ onto the Square Torus plot ?
 overlayRFZ = 0,
! if reducetoRFZ=0, then should we symmetrize the dataset ?
 symmetrize = 0, 
! if symmetrize = 1, should we also display the orientations with negative scalar quaternion part ?
 shownegativeq0 = 0,
! use logarithmic intensity for square torus plot (not for the zone plate)
 logarithmic = 0,
! the default background color is black (b), but sometimes a white (w) background provides a better map
 background = 'b',
! compute the Riesz energies and compare to the optimal energies ? [this can take a while ...]
 doRiesz = 0,
! size of the output image (2n+1 x 2n+1)
 n = 500,
! number of parallel threads to use
 nthreads = 12, 
! square torus tiff image file (relative to EMdatapathname, WITHOUT EXTENSION!!!)
 sqtfile = 'undefined',
! zone plate tiff image file (relative to EMdatapathname, WITHOUT EXTENSION!!!)
 zpfile = 'undefined',
! hdf file name for full projection output
 hdffile = 'undefined',
 /

The first parameter pgnum represents the point group symmetry; this is folled by anglefile, which is an array of up to five strings, each representing an orientation input file. As listed in the comments, several input formats are available; at least the first string must be changed from undefined to the orientation filename. One can then reduce the orientations to the Rodrigues Fundamental Zone with reducetoRFZ, produce a line overlay of the RFZ with overlayRFZ, symmetrize the data set (i.e., apply point group symmetry, which is kind of the opposite of reducing to the RFZ) with symmetrize, display all the orientations with negative quaternion scalar part (normally only those with positive scalar part are shown) using shownegativeq0. The user can rescale from linear intensity profile to logarithmic with logarithmic and change the background from black to white using background. The parameter doRiesz activates the computation of the Riesz energy, which is a measure for the uniformity of the orientation distribution; this is meaningless for a non-uniform texture, and it can take quite a while to perform the computation for a uniform dataset. The size of the output image can be set with n, and the number parallel threads to be used for the simulation is set with nthreads. Finally, there are three output types: sqtfile generates three individual grayscale square torus maps as well as the combined RGB image; zpfile overlays a zone plate on the individual images (see papers listed above, only meaningfull for uniform datasets); and one can also store the numerical square torus map arrays into an HDF5 output file hdffile.

Then execute the program as follows (by default, filename.nml will be EMCliffordTorus.nml, in which case it can be omitted, but any filename can be used):

EMCliffordTorus filename.nml

As an example, let's use the EMsampleRFZ program with samplemode set to 'MIS' for misorientation ball sampling with a radius of $20^{\circ}$. We produce two orientation files, one for the cubic texture by setting rodrigues to $(0,0,1,0)$, and one for a Goss texture with rodrigues set to $(1,1,0,0.41421357)$ (the last entry is $\tan(\omega/2)$ with $\omega=\pi/4$). The resulting color maps are shown below with the cube texture on the left, the Goss texture in the middle, and the combined texture on the right.

\