Foil Defect Configuration Definitions

Foil and Defect Geometry Descriptions

The EMsoft package has several programs that allow for the computation of image diffraction contrast, either in SEM or TEM mode. All these programs require (in addition to program specific parameters) that the user set up the sample/foil geometry, and, within that geometry, the configuration and types of defects. In this wiki page, we describe the format for both input files, since they are common to many SEM and TEM programs. Be sure to read the two comments at the bottom of this page!

In the present version (4.0) of EMsoft, only a limited number of defect types is available (see next section); in a later version, we will add displacement fields derived from Molecular Dynamics simulations, Phase Field simulations, and Discrete Dislocation Dynamics simulations. At first, these will only be available for the STEM-DCI modality; at a later time, they will become available for ECCI imaging as well. We will also add Eshelby ellipsoidal inclusions as a defect option.

Foil description file

The foil (or the bulk sample for the ECCI modality) is described by a number of parameters that define the thickness and orientation, as well as the (anisotropic) elastic moduli of the material. The file format is .json, and the contents are as follows:

 {
     "FoilDescriptor": {
         "foilF": [ 0.0, 0.0, 1.0 ],
         "foilq": [ 1.0, 0.0, 0.0 ],
         "foilalP": 0.0,
         "foilalS": 0.0,
         "foilalR": 0.0,
         "foilz0": 100.0,
         "foilelmo": {
             "row1": [ 168.4, 121.4, 121.4, 0.0, 0.0, 0.0 ],
             "row2": [ 121.4, 168.4, 121.4, 0.0, 0.0, 0.0 ],
             "row3": [ 121.4, 121.4, 168.4, 0.0, 0.0, 0.0 ],
             "row4": [ 0.0, 0.0, 0.0, 75.5, 0.0, 0.0 ],
             "row5": [ 0.0, 0.0, 0.0, 0.0, 75.5, 0.0 ],
             "row6": [ 0.0, 0.0, 0.0, 0.0, 0.0, 75.5 ]
         }
     }
 }

foilF is the foil normal specified as direction indices (real-valued); foilq is the reciprocal space direction that points along the primary tilt axis of the sample holder which can be derived from an electron diffraction pattern. This direction will be the horizontal direction in the simulated image. foilalP and foilalS are the tilt angles (positive for counterclockwise) for the Primary and Secondary tilt axes of a double tilt holder; foilalR is the rotation angle for a rotation-tilt holder. The foil thickness (in nm) is defined by foilz0. Finally, the array foilelmo contains the elastic moduli tensor expressed as a 6x6 matrix. Note that the units are not important, as long as all entries are expressed in the same units; they are normalized during the computation.

The simulated image will have dimensions of Nx by Ny pixels, and the dimensions are typically set in the name list file for the program that performs the image simulations. To define the defects (details in the next section), a coordinate grid is superimposed on the simulated image. Along each direction (horizontal and vertical), the "defect space" has a coordinate range of [-1, +1], which puts the origin at the center of the image. Each pixel has a particular physical size equal to the column width defined by the user (column approximation); the combination of the column width and the number of image pixels sets the image magnification.

Defect description file

While name list files are the default for nearly all EMsoft program input, the foil and defect input files are specified in a different format: the Java Script Object Notation or JSON format, with text files that have the extension .json (or .jsonc, see comment at bottom). This format is a little more verbose in terms of formatting requirements, but it is better suited for the definition of foil and defect geometries than the standard .nml format. The defect description file contains full descriptions of each individual defect; the following defect types are available: straight dislocations (perfect or partial), stacking faults, spherical inclusions, and voids.

• dislocations: these are straight dislocations, with arbitrary line direction and Burgers vector. For TEM image simulations, the displacement field is described by the standard form for dislocations in an elastically anisotropic medium; for ECCI simulations on the other hand, we need to include the surface relaxations that occur when a dislocation penetrates the surface. Basic expressions for such dislocations in an elastically isotropic medium were derived by Yoffe [The angular dislocation, Phil. Mag., $$5$$:161-175 (1960)] and later corrected by Shaibani & Hazzledine [The displacement and stress fields of a general dislocation close to a free surface of an isotropic solid, Phil. Mag. A, 44:657-665 (1981)]. Both dislocation types are available for image simulations, regular for TEM, and Yoffe for ECCI.
• stacking faults: SFs can be defined in terms of their fault plane and the bounding partial dislocations; the SF displacement vector is taken to be the Burgers vector of the leading partial. SFs can intersect the foil surface, and multipl SFs can overlap in the beam direction. A stacking fault can thus cross the entire field of view, or be bounded on one or both sides by a partial dislocation.
• Spherical inclusions: these are the standard Ashby & Brown spherical inclusions with a lattice misfit. The input parameters are the radius, the misfit parameter, and the coordinates of the center.
• voids: voids are easy; they are spherical with a given radius, located at a particular coordinate in the foil, and they are empty (i.e., the scattering matrix simply propagates through vacuum).

The defect coordinates are defined with respect to the foil reference frame described above.

The defect configuration .json file has the following structure:

 {
     "DefectDescriptors": {
         "foil": {
             "foilfilename": "EMfoil.json"
         },
         "dislocations": [
                 {
                     "id": 0.001,
                     "jd": 0.001,
                     "u": [ 0.0, 0.0, 1.0 ],
                     "bv": [ 0.5, 0.5, 0.0 ],
                     "zfrac": 0.0
                 },
                 {
                     "id":-0.501,
                     "jd": 0.251,
                     "u": [ 0.0, 0.0, 1.0 ],
                     "bv": [-0.5, 0.5, 0.0 ],
                     "zfrac": 0.0
                 },
                 {
                     "id": 0.501,
                     "jd":-0.251,
                     "u": [ 0.0, 0.0, 1.0 ],
                     "bv": [ 0.5,-0.5, 0.0 ],
                     "zfrac": 0.0
                 },
         ],
         "Ydislocations": [
                 {
                     "id": 0.001,
                     "jd": 0.001,
                     "u": [ 0.0, 0.0, -1.0 ],
                     "bv": [ 0.5, 0.5, 0.0 ],
                     "poisson": 0.31
                 }
         ],
         "stackingfaults": [
                 {
                     "SFi": 0.001,
                     "SFj": 0.001,
                     "SFsep": 100.0,
                     "SFplane": [ 1.0, 1.0, 1.0 ],
                     "SFlpu": [ 1.0, 0.0, -1.0 ],
                     "SFlpb": [ 0.3333, 0.3333, 0.3333 ],
                     "SFtpu": [ 1.0, 0.0, -1.0 ],
                     "SFtpb": [-0.3333, 0.3333, 0.3333 ]
                 },
                 {
                     "SFi": 0.401,
                     "SFj": 0.301,
                     "SFsep": 60.0,
                     "SFplane": [ 1.0,-1.0, 1.0 ],
                     "SFlpu": [ 1.0, 0.0, -1.0 ],
                     "SFlpb": [-0.3333,-0.3333, 0.3333 ],
                     "SFtpu": [ 1.0, 0.0, -1.0 ],
                     "SFtpb": [ 0.3333,-0.3333, 0.3333 ]
                 }
         ],
         "voids": [
                     [ 0.0, 0.0, 0.25, 5.0 ],
                     [ 0.2, 0.3, 0.5, 15.0 ],
                     [ 0.0, 0.0, 0.0, 5.0 ]
         ],
         "inclusions": [
                     [ 0.0, 0.0, 0.0, 5.0, 0.01 ],
                     [ 0.6, 0.2, 0.3, 4.0, 0.02 ]
         ]
     }
 }

At the top of the file, foilfilename defines the name of the foil descriptor file; this follows the usual convention for file path names, but see the comment at the bottom of this page for Windows users.

Note that each defect type consists of a block (delineated with square brackets) of defect descriptors, which each have a number of fields; there is no limit to the number of defects that can be defined for each type. For dislocations, (id,jd) represent the fractional coordinates in the foil reference frame introduced above of the center of the dislocation in the foil, i.e., the intersection of the dislocation line with the mid-point of the foil. u and bv are the line direction and Burgers vectors, respectively. If the line direction is normal to the foil normal, then the user must specifiy, in addition to (id,jd), the depth of the dislocation in the foil; this is defined as a fractional depth of the foil thickness with respect to the center plane. This means that zfrac is in the interval [-0.5, +0.5], with -0.5 the top of the foil. Note that the displacement field of any dislocation contains a logarithmic divergence; to make sure that this divergence doesn't cause artefacts in the image simulation, it is a good idea to place dislocations not precisely on image grid points, but introduce small deviations (typically 0.001 is large enough) from the grid points.

For Yoffe dislocations (Ydislocations), the parameters are identical as for regular dislocations, with the exception that the displacement field is always for an elastically isotropic material, hence the poisson parameter. The line direction should always point into the sample surface, i.e., the dot product of line direction and foil normal should be negative.

Stacking faults require several parameters; (SFi,SFj) are the coordinates of the center of the fault (in the center plane of the foil); SFsep is the separation between the partials in nm, i.e., it is the stacking fault length inside the foil mid plane. SFplane is the stacking fault plane normal. The remaining variables are the line direction and Burgers vector for the leading partial (lp) and the trailing partial (tp). The stacking fault displacement vector will be equal to the Burgers vector of the leading partial.

Voids are spherical and require the definition of 4 parameters, namely the fractional coordinates in the foil reference frame, the depth as a fraction of the foil thickness, and the radius in nm. The number of voids is unlimited.

Finally, the spherical Ashby-Brown inclusions require 5 parameters each, namely the three coordinates (similar to voids), the radius in nm, and the C parameter defined by 3Kd(1+nu)/[3K(1+nu)+2E], where $d$ is the lattice misfit d=(a_p-a_m)/a_m, K the bulk modulus, E the Young's modulus, and nu the Poisson ratio. Note that K and E must be expressed in the same units.

Comment regarding .json and .jsonc files

Standard .json files do not allow for comment lines, so it is a bit more difficult to document the meaning of all the parameters. In the next version of EMsoft, we will introduce an intermediate format with extension .jsonc, which is a commented json file; following the fortran standard, comment lines start with the character ! in the first character spot, but otherwise follow the .json standard. There is no limit to the number and location of comment lines in a .jsonc file. When an EMsoft program reads a .jsonc file, it will first strip out the comment lines and then pass the stripped file to the JSON parser routine. The original input file remains intact and, depending on the program, will be written in its entirety to the output HDF5 file.

Comment regarding file paths

The json standard employs the / character (forward slash) to delimit folders in file paths, regardless of the operating system on which the .json file is used. This means that on Windows systems, file paths inside a .json file must use the UNIX / delimiter instead of the Windows \ delimiter. Hence, when specifying the location of the foil description file inside the defect input file, the path should only use the / character, regardless of the operating system; using the \ slash on Windows machines results in an invalid .json file, and the parser will not be able to read the input parameters.