The Swiss-army knife of atomic simulations

Tutorial: Options and Modes

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

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.

What Atomsk actually works with:

What Atomsk does not work with:

ⓘ When converting files with Atomsk, do not be surprised if some parameters are lost. It simply means that Atomsk cannot treat such information, as it only deals with atom positions and properties.

The "options" in Atomsk are transformations that can be applied to the system. Such transformations only apply to atom positions, their properties, and/or to the cell vectors. For example, options are available to duplicate an atomic system, or to introduce defects, and so on.

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.

1. 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:


# Fcc Al oriented X=[100], Y=[010], Z=[001].
4.02000000 0.00000000 0.00000000
0.00000000 4.02000000 0.00000000
0.00000000 0.00000000 4.02000000
4.02000000 0.00000000 0.00000000
0.00000000 4.02000000 0.00000000
0.00000000 0.00000000 4.02000000
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.

2. Options

In Atomsk, an "option" is a transformation applied to an atomic system. 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").

3. Modes

By default, Atomsk reads one input file and writes one or many output files. A "mode" modifies this behavior. Only one mode can be used at a time. The mode is specified with a double dash (--), and can be followed by one or more parameters.

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.

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".