Back to main menu

## Mode: polycrystal

#### Syntax

`atomsk --polycrystal <seed> <param_file> <outputfile> [<formats>] [options]`

#### Description

This mode generates a polycrystal from a given <seed>, using the Voronoi tesselation method and the parameters provided in the file <param_file>. The positions and crystallographic orientations of the grains can be given explicitely, or generated randomly.

The file <seed> must contain an atomic system in one of the supported formats. Usually the seed is a unit cell of a material (such simple systems can be created thanks to the mode `--create`). However the <seed> can also be a supercell, a large system containing defects, a polycrystal, or any arbitrary atomic system.

The <param_file> is a text file that must contain keywords followed by appropriate values. Empty lines, and lines starting with the hash symbol (#), are ignored.

The keyword box is mandatory and must appear before any other keyword. It must be followed by three real numbers defining the size of the final box (in Å). The final box can only be a parallelepiped.

The keyword random <N> can be used to generate a random structure containing <N> grains. The positions and crystallographic orientations of the grains will be decided randomly by the program. Note that this method attempts to generate random numbers, therefore it is largely non-reproducible, i.e. starting from the exact same <param_file> and constructing a polycrystal with the present mode will most likely lead to different results. Atomsk will write a new parameter file, with a name ending with "_param.txt", and containing the random positions and orientations generated. This new parameter file can be used to reproduce the same polycrystal.

With the keyword lattice, followed by a lattice type, the positions of the grains will be set according to the given lattice type. The lattice types are "bcc", "fcc", "diamond", "hcp". For instance with an fcc lattice, seeds will be placed at each corner of the box and at the center of each face. The crystallographic orientation of the grains will be randomly decided by the program.

The keyword node can be used to define explicitely the position (x,y,z) and orientation of a grain. The cartesian coordinates x, y, z, are usually given in Å. It is also possible to give them with respect to the box dimensions with the keyword BOX and an operation (see this page). For each grain, the crystallographic orientation can be specified in one of the following ways:

- as Miller indices (see how to specify Miller indices). Note that this assumes that the orientation of the <seed> is X=[100], Y=[010], Z=[001].
- as rotation angles, by entering three real numbers (the degree symbol [°] may be appened to the numbers, but is not mandatory). The seed will be rotated by the first angle around the cartesian X axis, then by the second angle around Y, and finally by the third angle around Z.
- "random", in which case the program will apply a random rotation matrix.

Each line starting with the keyword node defines one grain.

The keywords random, lattice, and node are mutually exclusive. Only one of them must be used in a parameter file.

The keyword clearance may be used to control the thickness of the area around grain boundaries where atoms are removed. All atoms within ±clearance of the boundary planes will be removed. The default is clearance = 0.1 Å.

By default the grains are constructed thanks to a 3-D Voronoi tesselation of space: the <seed> is placed at the position of each node, and expanded into the Voronoi polyhedron. Periodic bounday conditions are used in the three dimensions of space.

If one dimension of the box is shorter or equal to the provided <seed>, then a 2-D Voronoi tesselation will be automatically used. The dimension of the final box along that direction will automatically be set to the dimension of the <seed>. If a random orientation of the grains is asked for, the lattice will only be rotated around the small axis, i.e. all grains will have the same crystallographic orientation along that axis. Note that afterwards, one can use the option `-duplicate` along that direction to generate a columnar structure.

If the initial <seed> contains shells (in the sense of an ionic core-shell model) they are duplicated along with the atoms (or cores). If auxiliary properties are defined for each atom in the initial <seed>, then the atom replica will be assigned the same auxiliary properties.

The mode `--polycrystal` will assign a new auxiliary property to each atom: its grainID, i.e. the index of the grain the atom belongs to. This allows to easily select grains with the option `-select`. Note that auxiliary properties can be written only to some file formats, e.g. Atomeye CFG format.

Once the polycrystal is generated, Atomsk will produce the additional following files:

- *_id-size.txt: text file containing the index of the grains (grainID), the number of atoms they contain, and their volume.
- *_size-dist.dat: data file (text file) containing the grain size distribution.
- *_nodes.xsf: file in the XSF format containing the positions of nodes used to generate the polycrystal. Each node is represented by a hydrogen atom.
- *_grains-com.xsf: file in the XSF format containing the positions of the centers of mass of the grains. Each center of mass is represented by a hydrogen atom.
- *_param.txt (only if the keyword "random" was used): text file containing the random numbers generated by Atomsk. This file complies with the format of the parameter file as described above (<fichier_param>), and can be used to generate an identical polycrystal.

If you use this mode with one or several options, then they will apply to the created system.

After generation of the polycrystal some atoms may not be inside of the simulation box, which can be fixed thanks to the option `-wrap`. Some atoms may also be too close to one another (at grain boundaries), which can be fixed thanks to the option `-remove-doubles`.

Beware that the system you create with this mode is not relaxed nor optimized.

#### Examples

- ##### voronoi_random.txt

  `# Voronoi polycrystal with 12 random grains
  box 250 250 200
  random 12
  `

  `atomsk --polycrystal fcc_unitcell.xsf voronoi_random.txt fcc_polycrystal.cfg lmp`

  This is the most simple way to construct a polycrystal with Atomsk. In the file `voronoi_random.txt` we ask for a system that is 250x250x200 Å3, made of twelve grains with random positions and orientations. The atom positions of the seed are in `fcc_unitcell.xsf`. The final polycrystal will be written into the files `fcc_polycrystal.cfg` and `fcc_polycrystal.lmp`.

- ##### voronoi_lattice.txt

  `# Voronoi polycrystal with a fcc arrangement
  box 200 200 200
  lattice fcc
  `

  `atomsk --polycrystal unitcell.xsf voronoi_lattice.txt polycrystal.cfg lmp`

  This will create a system of size 200x200x200 Å3, where grains are arranged like an fcc lattice.

- ##### my_polycrystal.txt

  `# Parameters for constructing a Voronoi polycrystal with atomsk
  box 300 300 300
  node 0 0 0 [100] [010] [001]
  node 40 80 60 56° -83° 45°
  node 80 60 90 [11-1] [112] [1-10]
  node 50 5 60 [110] [1-10] [001]
  node 0.75*box 0.75*box 0.95*box -31.4° 28.7° 90.0°
  node 60 100 80 random
  `

  `atomsk --polycrystal fcc_unitcell.xsf my_polycrystal.txt fcc_polycrystal.cfg lmp`

  This will build a polycrystal in a box of size 300x300x300 Å3. The position of each grain is given explicitely. The crystallographic orientation of some grains is given by Miller indices, for some others by the rotation angles. For the last grain, the program will generate a random crystal orientation.

- ##### bcc_polycrystal.txt

  `# Parameters for constructing a columnar Voronoi polycrystal with atomsk
  box 300 300 0
  random 12
  `

  `atomsk --polycrystal bcc_unitcell.xsf bcc_polycrystal.txt bcc_polycrystal.xsf -wrap -duplicate 1 1 16`

  Assume that the file `bcc_unitcell.xsf` contains a unit cell of a bcc metal with lattice parameter 2.9 Å. The file `bcc_polycrystal.txt` indicates to build a system that is 300x300x0 Å3, with twelve grains generated randomly. Because the system's dimension along the Z direction (0 Å) is smaller than the unit cell, it will automatically be modified to the lattice parameter (2.9 Å) and a 2-D Voronoi crystal will be constructed, i.e. all grains will have the same crystallographic orientation along Z. After the polycrystal is generated, the option `-wrap` will wrap all atoms inside the simulation box. Finally, the option `-duplicate` will repeat the system 16 times along Z, creating a columnar system.

- You may also want to look at the scripts in the "examples" folder provided with the program. The folder "`Al_polycrystal`" contains a bash script that builds a polycrystal of f.c.c. aluminium. The folder "`Fe_polycrystal`" illustrates how to create a polycrystal of b.c.c. iron. The folder "`MgO_2Dpolycrystal`" contains a bash script that builds a 2-D polycrystal of rocksalt magnesium oxide (MgO).

Back to main menu