This tutorial explains how to generate 3-D or 2-D polycrystals, containing grains of random or specific positions and orientations.
The mode "--polycrystal", as its name suggests, aims at creating a polycrystal.
In the following examples, a unit cell of aluminium will be used as a seed. Such a unit cell can be generated with:
atomsk --create fcc 4.046 Al aluminium.xsf
Atomsk uses a Voronoi tesselation to construct polycrystals, as illustrated in the figure below.
(a) Nodes (black dots) are introduced at given positions inside the simulation box.
(b) Nodes are linked with their neighbors (red lines). Periodic boundary conditions are used.
(c) The normal to the red lines are found (blue lines). These blue lines define the contours of the future grains, i.e. the grain boundaries.
(d) Atomic "seeds" (for instance unit cells) are placed at the positions of the nodes, with the given crystal orientation.
(e) A seed is expanded in the three directions of space. Atoms that are outside of the grain are removed.
(f) After all seeds have been expanded and cut inside their respective grains, one obtains the final polycrystal.
This illustrates the generation of Voronoi polycrystal in 2-D, but can be generalized to the 3-D case.
Let us start with a random polycrystal. Only two informations are needed: the dimensions of the final box, and the number of grains that it must contain. With this information, Atomsk will generate random positions for the nodes, and random crystal orientations for each grain.
First, the parameters must be written into a text file. For instance, to generate a polycrystal with 12 grains inside a box of size 200x200x200 Å3, create a file like this:
box 200 200 200
Then, run Atomsk in mode "--polycrystal", using "aluminium.xsf" as a seed and the text file created above:
atomsk --polycrystal aluminium.xsf polycrystal.txt final.cfg
The final system is written into "final.cfg", in Atomeye CFG format. Atomsk creates a new auxiliary property named "grainID". This property indicates, for each atom, the grain index (here from 1 to 12). The generated polycrystal can then be visualized, e.g. with Atomeye (use Alt+0 to visualize the grainID):
Atomsk also produces a data file (here "final.dat") containing the grain size distribution. It is a text file that may be opened with a text editor, or visualized as a graph:
It is important to note that "random" means that the numbers generated by Atomsk are different every time, and hence the generated polycrystal is different every time. If you try the command above, your polycrystal may look very different from the one in the picture. It will also be different every time you run the same command again.
When constructing a polycrystal, the unit cells are expanded into their Voronoi polyhedra using Cartesian coordinates. So, after the generation of the polycrystal, some atoms may be located outside of the simulation box. You will realize that if you visualize the system e.g. with OVITO:
Note that many visualization software (like Atomeye) automatically wrap atoms, i.e. they always display atoms as if they were inside the box. But, if you open the file ("final.cfg") and look at the atom positions, you will find that some atoms are actually outside of the box. It is also recommended to read the tutorial about boundary conditions.
If you wish to apply periodic boundary conditions, so that all atoms are really inside of the box, then use the option "-wrap" when constructing the polycrystal, for instance:
atomsk --polycrystal aluminium.xsf polycrystal.txt final.cfg -wrap
Sometimes it is preferrable to control the positions and/or the orientations of the grains. Again the size of the final box must be given. Then, each grain must be defined with a line starting with the keyword "node", followed by the position of the grain (three real numbers) and its crystal orientation. For example:
box 200 180 210
node 0 0 0   
node 40 80 60 56° -83° 45°
node 0.8*box 0.6*box 0.9*box [11-1]  [1-10]
node 50 5 60  [1-10] 
node 0.75*box 0.3*box 0.45*box -31.4° 28.7° 90.0°
node 60 100 80 random
Such a parameter file is interpreted as follows:
(1) The box will have dimensions 200 Å x 180 Å x 210 Å.
(2) The first grain will be positionned at the origin (0,0,0), and will be oriented X=, Y=, Z=.
(3) The second grain will be positionned at (40,80,60) (in Å), and the crystal will be rotated by 56° around the X axis, then -83° around Y, and then 45° around Z.
(4) The third grain will be positionned at the reduced coordinate (0.8,0.6,0.9). Note how the keyword "box" is used to specify reduced coordinates. This grain will be oriented X=, Y=, Z=.
(5) The last grain will be positionned at (60,100,80) (in Å), and will have a random orientation.
And so on. The various possible notations can be mixed up as in this example, but you may find it easier to use the same notation throughout your file. For instance specify all coordinates in Å (or all in reduced coordinates), and specify all orientations in degrees.
After generating your text file, run Atomsk with the same command as before:
atomsk --polycrystal aluminium.xsf polycrystal.txt final.xsf cfg
This time Atomsk will use the positions and orientations that you have specified, and the final polycrystal will look as follows:
Finally, Atomsk allows to construct 2-D polycrystals. To do so, simply set one box dimension to zero, as in the following example:
box 200 200 0
Atomsk will automatically replace the zero value by the actual size of the seed along that dimension. Here we use a unit cell of aluminium of lattice constant 4.046 Å as a seed, therefore Atomsk will automatically set the box dimension to 4.046 Å along the Z direction. Since the polycrystal is 2-D, all the grains will have their  axis aligned with the Z direction, and the grains will only be rotated around the Z axis. This is what the final system looks like:
As before, it is also possible to specify the positions and orientations of the grains manually in a 2-D polycrystal.
If you wish to have another crystal direction along the Z axis, then the original seed has to be oriented accordingly. For instance, the file "aluminium.xsf" used above should have the desired lattice orientation. You may follow this tutorial to learn how to generate oriented unit cells with Atomsk.
The capability to construct 2-D polycrystals can be used to generate grain boundaries, as explained in the following tutorial.
Furthermore, it is possible to generate multi-phase polycrystals. Read this tutorial to know more.