STEM DCI Image Simulations

STEM-DCI Image Simulation Programs

This wiki page covers the two STEM-DCI simulation programs (EMDispFieldSTEM and EMAtomCoordSTEM) which accept material models output as input data containing dislocation information.

EMDispFieldSTEM

The EMDispFieldSTEM program simulates Scanning Transmission Electron Microscope-Defect Contrast Images (STEM-DCI) of dislocation configurations defined by a pre-computed array of displacement vectors, which describe the strain due a dislocation. Simple test configurations, such as a straight dislocation in an isotropic lattice, can be generated using closed-form expressions for the displacement field. For more complex dislocation configurations, modeling such as Discrete Dislocation Dynamics can be used. Molecular Dynamics output data can also be averaged into a discrete displacement field and used as input for this program, as long as displacement vectors for each atom are available.

EMDispFieldSTEM requires three files to be present in order to run: a .xtal file describing the crystal structure, an h5 file describing the displacement field, and a namelist file. Running EMDispFieldSTEM -t generates the namelist template file EMDispFieldSTEM.template. This will need to be renamed to EMDispFieldSTEM.nml, and includes the following entries:

 &STEMDCIlist
! DO NOT CHANGE THIS LINE
!------------------------
! IO Filenames
!------------------------
! Name of the crystal structure file
 xtalname = 'undefined',
! Name of the file containing displace vectors
 inputfilename = 'undefined',
! Output file containing diffracted intensities
 datafile = 'undefined',
!------------------------
! Diffraction Parameters
!------------------------
! Accelerating Voltage, in kV
 voltage = 200.0,
! Smallest d-spacing to take into account [nm]
 dmin = 0.08,
! Convergence angle of the beam cone, in mRad
 convergence = 3.0,
! Number of rings in the beam cone discretization
 discsize = 81,
!------------------------
! Crystal Parameters
!------------------------
! Crystal orientation Euler angles
 eu = 0.0, 0.0, 0.0,
! Nearest zone axis in this orientation
 ZAindex = 0,0,1,
! Laue center coordinates
 lauec = 0,0,
! Distance between points in the Z direction in the displacement field, in nm
 thk = 4.0,
! Number of subslices to use for each displacement point.
subslice = 20,
!------------------------
! OpenCL Parameters
!------------------------
! Device ID for GPU
 devid = 1,
! Platform ID for GPU
 platid = 1,
!------------------------
! Parameters for DDD simulations
!------------------------
! Is the data presorted into a 4D array in an h5 file?
 presorted = .True.,
! Scaling factor for input data that is not presorted, (x,y,z,dx,dy,dz)
! If you used a python script similar to the one in the 'resources' folder, to
! format your data as an h5 file, this is not used
 scalefactor = 1,1,1,1,1,1,
/ 

Many of these parameters are self-explanatory. Convergence sets the convergence angle of the incident beam cone in nm. Discsize defines the number of rings which are used to discretize the beam cone, not the total number of beams used in the discretization. The thk parameter defines the real space between each point in the displacement grid. The subslices parameter is used to limit errors that can arise due to the large values of thk: subslices should be set such that thk/subslices <= 0.2 nm.

Of particular note are the presorted and scalefactor parameters. In the Resources folder, there is an example script called DDD_CSV_Presorter.py which will convert a 2D list of displacement vectors and coordinate grids into a 4D array stored as an h5 file. This script may need to be modified if your input file is not formatted in the same way as the example file. If this script is used to format the input file, the presorted parameter can be left as the default '.True.' value. Only if the data is in a 2D array should the presorted parameter be changed to false. The scalefactor parameter defines the scaling of the displacement field in each dimension (x,y,z,dx,dy,dz). If the presorted value is '.True.', then the values in this array are not used.

If the input data is in the form of atom coordinate with associated displacement vectors, the python script MD_Disp_Average.py can be used to produce a presorted H5 file, similar to the output of the presorter script described above. This file can then be used as input to EMDispFieldSTEM.

Note that the zone axis is set using the ZAindex parameter. The EMZAgeom utility program can be used to obtain information regarding the coordinate grid used for the CBED pattern. When executing this command line program for an FCC structure and the [111] zone axis direction, the relevant part of the output looks as follows:

 Zone Axis :[  1  1  1]

 Crystal point group           :  m-3m
 Crystal point group number    : 32
 Laue group                    :  m-3m
 Diffraction group             : 6RmmR
 Diffraction group number      : 24
 Projection diffraction group  : 6mm1R

 Bright Field symmetry         :    3m1
 Whole Pattern symmetry        :    3m1
 Dark Field general symmetry   :     1
 Dark Field special symmetry   :     m

 Reciprocal lattice vectors : (  0 -1  1) and (  1  0 -1)

 --> Note that the first of these vectors is by default the horizontal direction in
     any diffraction pattern or image simulation. All reference frames are right-handed.

The values input for the lauec parameter will shift the center of the pattern along these reciprocal lattice vectors. This shift is primarily important if an annular detector model will be used to integrate the diffracted intensity, as these correspond to a shift in the CBED pattern.

Once all the parameters have been set, the program can be executed with the following command:

EMDispFieldSTEM

This program can take a significant amount of time to run, primarily depending on the number of grid points in the input data, the value of dmin, and the number of beams used to discretize the incident beam cone. After the program has run to completion, EMIntegrateSTEM should be used to integrate the diffraction data into an image.

EMAtomCoordSTEM

Similarly to EMDispFieldSTEM, EMAtomCoordSTEM can be used to simulate STEM-DCI from materials models. In this case, the input data is atom coordinates, such as those produced by molecular dynamics simulations.

This data can also be used with the EMDispFieldSTEM provided that there are displacement vectors associated with each atom in the simulation volume. If these vectors are not available, images can be computed directly from the atom coordinates themselves. However, this algorithm is slower than the displacement field based approach and can produce errors if the crystal parameters are not defined carefully to match those present in the data, so if possible it is preferable to use the displacement fields. This usage is described in the previous section.

Three files are required to run EMAtomCoordSTEM: an h5 file containing the atom coordinate data, a .xtal file describing the ideal crystal structure, and a namelist file. The command EMAtomCoordSTEM -t will produce a template file EMAtomCoordSTEM.template which can be modified and renamed to EMAtomCoordSTEM.nml. This file contains the following entries:

 &STEMDCIlist
! DO NOT CHANGE THIS LINE
!------------------------
! IO Filenames
!------------------------
! Name of the crystal structure file
 xtalname = 'undefined',
! Name of the file containing displace vectors
 inputfilename = 'undefined',
! Output file containing diffracted intensities
 datafile = 'undefined',
!------------------------
! Diffraction Parameters
!------------------------
! Accelerating Voltage, in kV
 voltage = 200.0,
! Smallest d-spacing to take into account [nm]
 dmin = 0.08,
! Convergence angle of the beam cone, in mRad
 convergence = 3.0,
! Number of rings in the beam cone discretization
 discsize = 81,
!------------------------
! Crystal Parameters
!------------------------
! Crystal orientation Euler angles
 eu = 0.0, 0.0, 0.0,
! Nearest zone axis in this orientation
 ZAindex = 0,0,1,
! Laue center coordinates
 lauec = 0,0,
! Distance between points in the Z direction in the displacement field, in nm
 thk = 4.0,
! Number of subslices to use for each displacement point.
subslice = 20,
!------------------------
! OpenCL Parameters
!------------------------
! Device ID for GPU
 devid = 1,
! Platform ID for GPU
 platid = 1,
!------------------------
! Computation Parameters
!------------------------
! Stride for interpolating the fourier coefficients
 stride = 0.0001,
! Maximum number of atoms to consider in a cell
 maxnumincell = 4,
/

Many of these parameters are the same as those described above for the EMDispFieldSTEM code. Please refer to that section for those descriptions.

The unique parameters for this code, compared to the displacement field code, are stride and maxnumincell. Stride determines the spacing for the interpolation grid computed for the Fourier coefficients of the lattice parameter. These values are precomputed in this code to increase computation speed, since the full scattering matrix is recomputed for every cell in this approach. Maxnumincell sets the maximum number of atoms in a cell that will be considered for the computation. You should set this value to the number of atoms you expect to be present in each cell based on your crystal structure and orientation. Note that mismatched atom counts in cells can lead to contrast differences on a per-pixel basis, so it is important that you properly segment your data such that each cell contains the same number of atoms as each other cell.

Once all the parameters have been set, the program can be executed with the following command:

EMAtomCoordSTEM

This program can take a significant amount of time to run, primarily depending on the number of grid points in the input data, the value of dmin, and the number of beams used to discretize the incident beam cone. After the program has run to completion, EMIntegrateSTEM should be used to integrate the diffraction data into an image.