6. Tags in Parameter file

The parameter file uses tags to configure CryDisGen: indication tags (Region, Loop, Tetrahedron, Helix) specify the atom region or dislocation type, counter tags (nTetrahedron, nLoop, nHelix) define the number of dislocation objects, and parameter tags (e.g., -x, -bv) set detailed properties.

6.1. Indication tags

Note

Indication tags in CryDisGen’s parameter file supply the information of the input atomic region or define dislocation objects being configured. There are Four indication tags in current version: Region, Loop, Tetrahedron and Helix. These tags specify either the input atom region (e.g., the crystal lattice) or the type of dislocation object to be introduced (e.g., a loop or tetrahedron), providing the structural context for subsequent counter and parameter tags. Each tag initiates a block of settings that CryDisGen uses to construct the corresponding atomic-scale feature.

Region:

It has no trailing parameter on the same line and indicates the following block of parameter tags defines the input atomic region. This section provides some additional parameters for the atomic region. In the parameter file, only one Region tag and its associated block is required. If multiple Region tags are included, code will exit with an error. If multiple blocks are present, the last one will override any previous ones, ensuring a single, final definition of the crystal region.

Loop:

It has no trailing parameters on the same line and indicates the following block of parameter tags defines a dislocation loop. In the parameter file, each dislocation loop instance corresponds to an independent Loop tag with its associated block of parameter tags. Multiple dislocation loops can be included in a single parameter file, and there is no limitation to their number.

Tetrahedron:

It has no trailing parameter on the same line and indicates the following block of parameter tags defines a stacking fault tetrahedron. In the parameter file, Tetrahedron can be abbreviated as Tetra. Each stacking fault tetrahedron corresponds to an independent Tetrahedron tag with its associated block of parameter tags. Multiple stacking fault tetrahedrons can be included in a single parameter file, and there is no limitation to their number.

Helix:

It has no trailing parameter on the same line and indicates the following block of parameter tags defines a dislocation helix. In the parameter file, each dislocation helix corresponds to an indipendent Helix tag with its associated block of parameter tags. Multiple dislocation helices can be included in a single parameter file, and there is no limitation to their numer.

6.2. Counter tags

Note

Counter tags in CryDisGen’s parameter file specify the number of dislocation objects to be generated using a following integer. There are Three counter tags: nLoop, nTetrahedron and nHelix. These tags are only required when the associated the dislocation instances are configured, and can be put anywhere in the parameter file. The integer value following each counter tag must match the number of indication tags; otherwies, code will exit with an error.

nLoop N:

The counter tag nLoop specifies the number N of dislocation loop sections to be defined in CryDisGen’s parameter file. The value N is a positive integer (e.g., 1, 2, etc.) indicating how many Loop sections follow in the file.

nTetrhedron N:

The counter tag nTetrahedron specifies the number N of stacking fault tetrahedron sections to be defined in CryDisGen’s parameter file. The value N is a positive integer (e.g., 1, 2, etc.) that indicates how many Tetrahedron sections follow in the file. It can be abbreviated as nTetra N.

nHelix N:

The counter tag nHelix specifies the number N of stacking fault tetrahedron sections to be defined in CryDisGen’s parameter file. The value N is a positive integer (e.g., 1, 2, etc.) that indicates how many Tetrahedron sections follow.

6.3. Parameter tags

Note

Parameter tags in CryDisGen’s parameter file define the detailed configuration settings for the crystal region or dislocation objects specified by indication tags (Region, Loop, Tetrahedron, Helix). Prefixed with a hyphen (e.g., -x, -bv, -tc), these tags follow their associated indication tag and provide specific values—such as coordinates, vectors, or scalars—that CryDisGen uses to construct the atomic-scale structure. Each parameter tag is tailored to its section’s context, ensuring precise customization of the simulation model.

Region:

#lines starting with '#' are comments
#crystal region
Region
-x     1 -1  0        # lattice orientation along x-axis
-y     1  1 -2        # lattice orientation along y-axis
-z     1  1  1        # lattice orientation along z-axis
-lat   3.615          # lattice constant
-pbc   1  1  1        # boundary condition flags along x/y/z-axex: '1' for periodic, '0'for non-periodic

Loop:

#dislocation loop
nLoop   1             # number of dislocation loops
Loop                  # label for dislocation loop section
-bv     1  1  1       # orientation of Burgers vector
-bs     1/3           # scalar coefficient of Burgers vector, e.g., 1/2 in 1/2<110>
-dnorm  1  1  1       # normal direction of dislocation plane
-dc     0.2 0  0      # center of dislocation loop
-dr     25            # radius of dislocation loop. For square shape, it is half the edge length.
-lx     1 -1  0       # local x-axis on dislocation plane
-ly     1  1 -2       # local y-axis on dislocation plane
-ndisl  4             # number of segments/vertices in a discretized dislocation loop

Important

Here, the local coordination system xoy on the dislocation plane is set by the parameter tags ‘-lx, -ly’, and is used to change the in-plane orientation of dislocation. A dislocation loop is approximated by an N-vertex equilateral polygon in geometry, where N is set by ‘-ndisl’. The position vector of the i-th vertex, where i = 1, 2, …, N, can be found by rotating the vector (1, 0) counterclockwise by an angle of (i-1)*2π/N in the xoy plane. For square-shape dislocation, the edges are set to parallel to axis, enabling straightforward coordinate-based calculations. If this is unnecessary in your case, the vectors following the tages ‘-lx, -ly’ can be simply set to ‘Null/null’ as what follows. Note that the ‘Null/null’ value should be used at the same time for tags ‘-lx, -ly’. Otherwise, code will exit with an error.

-lx      Null
-ly      Null

Tetrahedron:

#stacking fault tetrahedrion
nTetrahedron 1        # number of stacking fault tetrahedra
Tetrahedron           # label for tetrahedron section
-tc      0. 0. 0.     # center of the bottom face of the tetrahedron
-tr      40           # radius of the circumscribed circle of the bottom face
-tnorm  -1 -1 -1      # outward normal direction of the tetrahedron's bottom face
-lxt     1 -1  0      # local x-axis at the bottom face
-lyt    -1 -1  2      # local y-axis at the bottom face

Helix:

#dislocation helix
nHelix  1             # number of dislocation helices
Helix                 # label for dislocation helix section
-bvh    1  1  1       # orientation of the Burgers vector for the helix
-bsh    1/2           # scalar coefficient of the Burgers vector
-f      mesh0.dat     # mesh file of the helical surface

Tip

The lines of tags in the parameter file can be arranged in any order. To enhancethe readability, it is recommended to group parameter tags defining the same dislocation instance or atomic region together into a block, placing them after the corresponding indication and counter tags, as illustrated in the examples above.

6.4. Tag argument list

The CryDisGen code in its current version can handle three types of lattices such as FCC, BCC, and HCP. All the demonstrated parameter files prior to this sections pertain to FCC/BCC structures. To distinguish the lattice types, CryDisGen utilizes the argument lists of Parameter tags to do this. For example, the -lat tag accepts one argument, a, for FCC/BCC lattice, but two arguments, a and c, for HCP lattice. In FCC/BCC lattice, the orientations are represented by the Miller indexes, and the related Parameter tags, such as -x, -y, -lx, and -bv, require three integers as arguments. In contrast, for HCP lattices, these orienation tags require four integers in each argument list, i.e., the Miller-Bravais indexes, see the example Dislocation in HCP structure. All the Parameter tags with varying argument number for different lattices are listed in the following table:

Paramater Tags	Description	Argument number (FCC/BCC)	Argument number (HCP)
-x	lattice orientation along x-axis	3 (the Miller Indexes)	4 (the Miller-Bravais Indexes)
-y	lattice orientation along y-axis	3 (the Miller Indexes)	4 (the Miller-Bravais Indexes)
-z	lattice orientation along z-axis	3 (the Miller Indexes)	4 (the Miller-Bravais Indexes)
-lat	lattice constants	1 ( a )	2 ( a and c )
-bv	orientation of dislocation’s Burgers vector	3 (the Miller Indexes)	4 (the Miller-Bravais Indexes)
-dnorm	normal direction of dislocation plane	3 (the Miller Indexes)	4 (the Miller-Bravais Indexes)
-lx	local x-axis on dislocation plane	3 (the Miller Indexes)	4 (the Miller-Bravais Indexes)
-ly	local y-axis on dislocation plane	3 (the Miller Indexes)	4 (the Miller-Bravais Indexes)
-bvh	orientation of the dislocation helix’s Burgers vector	3 (the Miller Indexes)	4 (the Miller-Bravais Indexes)

Warning

All the parameter tags listed in the above table within a single parameter file must be set with the arguments corresponding to the same lattice type. Otherwise, the CryDisGen code cannot properly detect the crystal structure, and will exit with an error such as “The Miller index in line 5 is NOT consistent with the parameter list previously set”.