Atomsk - Tutorial - Basics, Options and Modes

Tutorial: Basics, Options and Modes

This tutorial explains the basic internal logic of Atomsk, and the meaning of "options" and "modes".

1. Types of data handled by Atomsk

Atomsk is a program that manipulates data about a system of atoms. With that said, it does not manipulate just any kind of data, and it has its own internal logic.

First of all, let us explicitely state what Atomsk does not work with: bonds, molecules, interatomic potentials, or any parameter related to a simulation in particular.

ⓘ When converting files with Atomsk, do not be surprised if some parameters are lost. It simply means that Atomsk cannot handle such information.

What Atomsk actually works with, for a system containing N atoms:

cell vectors, stored in a 3×3 array H
atom positions, saved in an array P of size N×4
shells positions, stored in an array S of size N×4 (only if an ionic core-shell model is used)
atom properties (charge, force, etc.), which values are saved in an array called AUX of size N×m, where m is the number of properties

The following tables summarize the data handled by Atomsk:

id	Atom positions
1	x₁	y₁	z₁	Z₁
2	x₂	y₂	z₂	Z₂
3	x₃	y₃	z₃	Z₃
⁞	⁞	⁞	⁞	⁞
N	x_N	y_N	z_N	Z_N

id	Shell positions
1	x₁	y₁	z₁	Z₁
2	x₂	y₂	z₂	Z₂
3	x₃	y₃	z₃	Z₃
⁞	⁞	⁞	⁞	⁞
N	x_N	y_N	z_N	Z_N

id	Properties
1	a₁	b₁	c₁
2	a₂	b₂	c₂
3	a₃	b₃	c₃
⁞	⁞	⁞	⁞
N	a_N	b_N	c_N

The array P contains the position (x,y,z) of each atom; a fourth column contains the atom's atomic number Z. This array is always allocated, with a size that matches the number of atoms.

The array S containing shell positions is used only in the framework of an ionic core-shell model potential (see our tutorial about core-shell model). If an atom has a shell, then the atomic number Z in S equals the atomic number Z in P; otherwise (i.e. if an atom has no shell, or it is a rigid ion), the value of Z in S is zero. If no core-shell model is used (or if no atom has a shell at all), then the array S remains unallocated, so as not to use any memory.

Finally, the array AUX is used only if some properties are defined on a per-atom basis, like electric charges, forces, velocities, and so on. The array AUX is allocated with a size that matches the number of auxiliary properties. For example, if three properties named A, B, C are defined, then they take the values a₁, b₁, c₁ for the first atom, a₂, b₂, c₂ for the second atom, and so on. Otherwise, if no property is defined, then AUX remains unallocated, and does not use any memory.

When reading a file, Atomsk loads the corresponding data in the arrays defined above. Any other data (like definitions of bonds, molecules, interatomic potential, etc.) are not saved, and are simply lost.

When writing a file, Atomsk writes the data from the arrays above into a file, using the appropriate format. Note that not all data can be written in all file formats. To know more, read our tutorial about auxiliary properties.

2. Convert a file

Atomsk was primarily conceived as a tool to convert files of atomic data. If you wish to practice the commands below, you may download the example file Al_unitcell.xsf. It is a text file containing the atom positions of a unit cell of aluminum, in the XSF format:

Al_unitcell.xsf

# Fcc Al oriented X=[100], Y=[010], Z=[001]. CRYSTAL PRIMVEC 4.02000000 0.00000000 0.00000000 0.00000000 4.02000000 0.00000000 0.00000000 0.00000000 4.02000000 CONVVEC 4.02000000 0.00000000 0.00000000 0.00000000 4.02000000 0.00000000 0.00000000 0.00000000 4.02000000 PRIMCOORD 4 1 13 0.00000000 0.00000000 0.00000000 13 2.01000000 2.01000000 0.00000000 13 0.00000000 2.01000000 2.01000000 13 2.01000000 0.00000000 2.01000000

This atomic system can be visualized with XCrySDen or with VESTA, as explained in the following tutorial.

Converting a file is easily achieved by giving the name of the input file, and the name of the output file, as command-line parameters to Atomsk. For instance:

atomsk Al_unitcell.xsf Al_final.cfg

The command above will read the file "Al_unitcell.xsf", and generate a file named "Al_final.cfg" in the CFG format, for visualization with AtomEye or OVITO.

If you wish to keep the same file name and just change the format, then simply specify the output format. For instance the following command will read the file "Al_unitcell.xsf", and generate the file "Al_unitcell.cfg":

atomsk Al_unitcell.xsf cfg

It is also possible to specify several output formats, and Atomsk will generate the corresponding files with the appropriate formats. For instance, the command:

atomsk Al_unitcell.xsf cfg lammps vasp

will generate the file "Al_unitcell.cfg" for visualization with Atomeye, the file "Al_unitcell.lmp" for a simulation with LAMMPS, and the file "POSCAR" for a simulation with VASP.

3. Options

The "options" in Atomsk are transformations that can be applied to the system. Options allow to transform atom positions (P), shells positions (S), auxiliary properties (AUX), and/or cell vectors. For example, options are available to duplicate an atomic system, or to introduce defects, and so on. Several options can be called in the same command line. Each option starts with a dash sign (-), and can be followed by one or more parameters.

For instance, the option "-duplicate", followed by the number of replicas along X, Y and Z, can be used to duplicate the initial system:

atomsk Al_unitcell.xsf -duplicate 2 2 3 Al_supercell.cfg

The sequence is as follows: Atomsk will read the file "Al_unitcell.xsf", then it will duplicate the system twice along X and Y, and three times along Z, and then write this duplicated system into the file "Al_supercell.cfg". Again this system may be visualized with AtomEye or OVITO.

If you wish to apply several transformations to your system, then use the appropriate options accordingly. For instance, if you wish to duplicate the system, and then deform it by 2% along X, then write the option "-duplicate" first and then the option "-deform", as follows:

atomsk Al_unitcell.xsf -duplicate 2 2 3 -deform X 2 0.33 Al_supercell.cfg

Atomsk will apply each option, one after the other, in the order that you give in the command-line. Here, the unit cell will first be duplicated, and then the duplicated system will be deformed. You may use as many transformations as you like in a single command-line. The final system, after all options have been applied, will be written in the specified output file (here "Al_supercell.cfg").

4. Modes

By default, Atomsk reads one input file and writes one or many output files. A "mode" modifies this behavior.

The "modes" in Atomsk allow to perform specific operations, constructions, analysis, or to manipulate several data files. For example the mode "--create" allows creating an atomic system from scratch; the mode "--polycrystal" can form bicrystals or polycrystals, and so on. Examples are given below and in the following tutorials. The mode is specified with a double dash (--), and can be followed by one or more parameters. Only one mode can be used at a time.

For instance, you may want to convert several files. The default mode, as described above, cannot do that because it takes only one file as an input. Atomsk can convert several files with the mode "--list", as explained in this tutorial.

As another example, you may want to merge several atomic systems into a single one. Again this is not possible with the default mode, so you have to use the mode "--merge". The mode "--merge" take several files as an input and merges them.

Yet another example: the mode "--create" allows to generate a new atomic system from scratch, so it does not need an input file. You will learn more about the mode "--create", and the visualization of your atomic systems with various softwares, in the following tutorial.

In more advanced tutorials you will learn how to use other modes, like the mode "--polycrystal".