Back to main menu
atomsk --polycrystal <seed> <param_file> <outputfile> [<formats>] [options]
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:
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.
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.
--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:
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
Beware that the system you create with this mode is not relaxed nor optimized.
# Voronoi polycrystal with 12 random grains
box 250 250 200
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
# Voronoi polycrystal with a fcc arrangement
box 200 200 200
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.
# Parameters for constructing a Voronoi polycrystal with atomsk
box 300 300 300
node 0 0 0   
node 40 80 60 56° -83° 45°
node 80 60 90 [11-1]  [1-10]
node 50 5 60  [1-10] 
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.
# Parameters for constructing a columnar Voronoi polycrystal with atomsk
box 300 300 0
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