Back to main menu

## FAQ - Frequently Asked Questions

### General

- What is Atomsk?

Atomsk is a command-line program designed for people who perform numerical simulations in the areas of materials physics or chemistry, as well as people who wish to make illustrations in those areas. Atomsk allows to build and manipulate atomic systems, and generate data files for a variety of programs to perform ab initio calculations, classical molecular dynamics simulations, TEM image simulations, or visualization.

- Why is that program named Atomsk ? How should I spell it?

Atomsk stands for Atom, Molecule, Material Software Kit. It is quite short which is convenient when you type it several times a day in your command-line, and the presence of the sound "atom" suggests that this code deals with atomic systems.

The program name should be spelled with an uppercase first letter, followed by lowercase letters, as follows: Atomsk. Other variants, like "atomsk" or "ATOMSK", should be avoided.

- Why create such a program?

After some time writing various small programs to design atomic systems, one quickly realizes that the same basic operations must be re-coded over and over again: building supercells, wrapping atoms into the box, deform the box, and so on. Therefore you end up copy/pasting the same routines (or worse, re-write them from scratch) for every different system (fcc, bcc, diamond lattices...). In addition, if you want to use another simulation or visualization software, you may have to re-write your codes to comply with the file formats of the target software.

I thought it would be more efficient to write a general-purpose program that could perform these operations in any system, no matter the atom species or the lattice, and no matter what the input and output formats are. Such is the purpose of Atomsk.

- What are the principles behind Atomsk?

Atomsk follows two principles. The first one states that when you want to do something simple, then it should be simple to do it. An example of something "simple" is to convert a file: we don't want to spend hours reading documentation just to figure out how to convert one file. That is why in Atomsk you have to enter only the two informations: the name of the file you want to convert, and the final file format, e.g.:

`atomsk file.xsf cfg`

A corollary of this principle is that when you want to do something complicated (build complex systems, compute some property...), then it may not be so simple to do it. Some programs allow to perform very complex tasks simply, but they are very specialized software -while Atomsk tries to be quite general and applicable to many systems.

The second principle is that when one reads a command-line of Atomsk, what it does should be obvious and non-ambiguous. For example the following command:

`atomsk --create fcc 4.02 Al -duplicate 10 10 4 supercell.xsf`

will obviously create a 10x10x4 supercell of fcc aluminum, and write it to the file `supercell.xsf`. This principle ensures that if you write such commands in scripts (e.g. bash scripts) and read them again months or years later, you will still be able to understand quickly what you did.

- Where can I download Atomsk?

It is recommended to visit the official Web site: http://atomsk.univ-lille.fr/

Download the executable binary for your platform. You can also download the source code if you wish to compile the code yourself or have a look at it.

- How should I cite Atomsk?

If you use Atomsk in your work, the citation of the following article will be greatly appreciated:

- Pierre Hirel, Comput. Phys. Comm. 197 (2015) 212

### Usage

- What type of systems can I construct with Atomsk?

Atomsk was primarily designed to construct and manipulate atomic systems for materials physics. It has facilities to construct supercells, insert defects (vacancies, interstitials, dislocations, cracks...), and to read and write file formats commonly used in that field.

Although Atomsk can read and write some file formats commonly used in chemistry or biology (DL_POLY, PDB, XYZ...), you may find it not so suitable for constructing molecular systems. Atomsk does not understand molecules, bonds, and lacks the common tools used to construct such systems (e.g. solvating).

- What is the precision on atomic positions?

Internally all real numbers are stored with 64-bits precision. When writing output files, supercell parameters and atom coordinates are written with 8 decimal digits. This is assumed to be sufficient for most applications.

- What is the maximum number of atoms that Atomsk can handle?

In principle the limit is that of 32-bits (4-bytes) integers, i.e. about 2 billions (231). In practice there are good chances that the amount of virtual memory available on the machine will be the limiting factor. Each atom is characterized by its position x, y, z, and its atomic number, which makes a total of four numbers that are saved as 64-bits real numbers: as a result each atom requires 256 bits or 32 bytes of memory. Storing all atoms requires an array of size Nx4, where N is the number of atoms. So, a system of one million atoms will use about 32 MB (or 30.5 MiB), 10 millions atoms will use 320 MB, and so on. So, in order to reach the limit of 2 billions of atoms you will need about 64 GB of memory.

In addition if your system includes shells (in the sense of an ionic core-shell model), it will require a second array of size Nx4. Finally if atoms have auxiliary properties (like forces, velocity...), these properties are also saved in a 64-bits real array of size NxM where M is the number of properties associated with each atom.

- What units are used?

By default angströms are assumed, although Atomsk just passes the numbers from one file format to another without caring about the units.

Note that Atomsk makes absolutely no implicit transformation of the units. For instance, if you read a file containing atom positions in Bohrs, then in the output file they will also appear in Bohrs. In order to explicitely convert the units of the atom coordinates and cell parameters you can use the option `-unit`.

- I am faced with a prompt (`atomsk>`) and I don't know what to do.

That means that you have run Atomsk without any argument, either by entering "atomsk" in your command-line, or double-clicking the executable or a link to it. This triggers the interactive mode. In this mode the program waits for your commands, and executes them in real-time (if they are valid). In this mode, type "help" to see a list of available commands.

If you do not wish to use Atomsk interactively, then you must run it in a command-line with trailing arguments, for instance:

`atomsk initial.xsf -duplicate 2 2 2 final.cfg`

- Where are the output files generated by Atomsk?

Atomsk writes files in the current working directory, i.e. the directory where you are when you run Atomsk. Type "pwd" to know the path to that directory, and "ls" to display the list of files in the directory.

- How do I change the language?

Atomsk tries to speak your language if it can; otherwise it defaults to English. If you wish to use a specific language, you can use the command-line option "-lang", followed by the two-letter code of your language. Please have a look at the list of supported languages.

To make the change more permanent, you can create your own configuration file. Please refer to this page to learn how to set up your own configuration file.

- How many options can I call in a single command-line?

There is virtually no limitation, apart from those of your shell itself. Try "`getconf ARG_MAX`" to know the maximum command line length that your shell supports.

- How can I create a unit cell?

Atomsk can create unit cells of some simple geometries thanks to the mode create. For instance, to create a unit cell of face-centered cubic aluminium (lattice parameter 4.02 Å) and write it to the file `aluminum.xsf`:

`atomsk --create fcc 4.02 Al aluminum.xsf`

However this method is pretty limited, as a lot of lattice types can simply not be generated at all. If you know the space group and Wyckoff positions of the crystal you want to build, then the Bilbao Crystallographic server can be extremely helpful to build the crystal. Some other codes can also generate crystal structures given the space group and the Wyckoff positions, like VESTA, ASE, or some simulation codes like XMD or GULP.

It is possible that Atomsk will include such methods in future releases, however this is not planned at the moment.

- I have a unit cell, how do I generate a supercell?

This can be done with the option `-duplicate`. If your unit cell is in the file `unitcell.xsf`, and you want to create a 4x4x2 supercell, the command would be:

`atomsk unitcell.xsf -duplicate 4 4 2 supercell.xsf`

and the supercell will be written in the file `supercell.xsf`.

- How can I convert a file for a specific simulation or visualization software?

Call Atomsk with the name of the input file and the target file format (check this page for a list of supported file formats). For instance, to convert the file "file.xsf" into the CFG format for Atomeye enter:

`atomsk file.xsf cfg`

Several file formats can be specified, e.g. the following will generate files in both CFG format (Atomeye) and LAMMPS data file format:

`atomsk file.xsf cfg lmp`

- I created an input file with Atomsk, but then my ab initio or molecular dynamics code does not run.

While it is true that one of the purposes of Atomsk is to help to prepare files for simulations, it is not meant to prepare all the files nor set all the parameters for your simulation. Most of the time, Atomsk will only prepare a draft that you will have to edit before running a simulation. Editing such an input file means that you must know what you want to do and how to do it with the simulation code(s) that you are using. If it is not the case, then don't expect Atomsk to help you: refer to the documentation of the code you are using.

- Is it possible to write scripts for Atomsk?

Yes, there are actually 3 ways to work with "script files" with Atomsk.

The first and natural way is to use bash scripts (or batch in Windows). Any variable defined in the bash script can be used in the command-line with atomsk, since these variables are automatically interpreted by the shell before running the command. All the examples provided with the code in the "examples" folder use this capability.

Second, it is also possible to write some options in a file, for instance:

##### my_options.txt

`# options for atomsk
duplicate 40 30 1
deform x 3% 0.33
`

and then run the program with the option `-options`, e.g.:

`atomsk unitcell.xsf -options my_options.txt final.xsf`

And, last but not least, it is also possible to write "atomsk scripts" and feed the program with it. This capability is detailed in the mode interactive.

- I do not like the way Atomsk always prints information on my screen, how do I change that?

The printing of information is the default behaviour of the program, as a way to tell exactly what it is doing. This default behaviour can be changed thanks to the command-line parameter `-verbosity`. For instance, to make the program completely silent, call it with `-v 0`.

To make this change more permanent, it is also possible to create a personal configuration file. If you are using a GNU/Linux system, create a file `~/.config/atomsk.conf` and write into it: `verbosity 0`.

Note that even when the verbosity is set to zero, warning and error messages will still be displayed on screen. To avoid that, use the standard redirection: `>/dev/null 2>&1`.

- When running Atomsk, it crashed.

The code is supposed to detect possible causes of errors and exit smoothly, but in some cases it is possible that it terminates abruptly due to a segmentation fault or any other form of error or crash. The latter behaviour is most likely caused by a bug in the program, and that can be anything. The best line of action is to report such a bug by sending an email to the author, with your input file and the complete command-line parameters that you used to run Atomsk. Hopefully the bug will be fixed in a future release.

Please note that if you only curse at the program (or the author) but do not report the bug, it is very unlikely to get fixed.

### Compilation / Installation

- The program won't compile with my compiler.

A lot of efforts were made to test the program with many different compilers (GNU Fortran, g95, Intel Fortran) on many platforms (different flavors of Linux and Windows), please check the installation page for a list of tested compilers. However for obvious reasons of limited available time and resources all possible environments were not tested -therefore it is still possible that, in some particular cases, the compilation will fail.

Some old versions of some compilers are known to cause problems with the present program. For instance Atomsk will not compile with gfortran 4.1, but compiles flawlessly with gfortran 4.4. The best is to use an up-to-date version of your compiler. If it still does not work, try with another compiler.

- When compiling I get the error message "undefined reference to dgesv_" (or a similar message).

That means that the compiler cannot link Atomsk to the LAPACK library. First, make sure that LAPACK is installed on your system, and compiled with the same compiler as the one you are using for Atomsk. Then, make sure that the `LAPACK` variable (in the Makefile you are using) points correctly to the LAPACK library.

- Does this program work on Windows XP, Vista, Seven, 3.1 or whatsoever?

Actually yes, Atomsk runs natively on Microsoft® Windows® systems. The most simple thing to do is to download the Windows executable (atomsk.exe) from the download page, and just run it.

If you are bold enough to try and compile the code under Microsoft® Windows®, follow the installation instructions page. You will have to install the program GNU Make for the "`make`" command to work, as well as a Fortran 95 compiler (MinGW is recommended). The LAPACK library is also needed, look at this page (GNU Fortran) and/or this page (Intel® Fortran). A Makefile for Windows is provided in the src directory (`Makefile.windows`), you may edit it to suit your system. Then run GNU Make by typing something like:

`make.exe -f Makefile.windows atomsk`

Alternatively Atomsk should also work under Windows in a Linux-like environment such as Cygwin, although this was not tested.

- Can you provide a package (rpm, deb...) for my favorite GNU/Linux distribution?

No. Although I admit it would be much desirable to have Atomsk packaged, I have neither the time or the knowledge of packaging processes to do it properly. Volunteers for this task are of course welcome.

As an alternative, binaries for Linux are provided on the atomsk Web page.

- On Linux, why does the program install in /usr/local/bin by default?

The package managers that come with most GNU/Linux distributions maintain their supported executables in the /usr/bin directory. So, first of all, you do not want to screw up this directory -that is why Atomsk does not touch it. The /usr/local/bin directory is actually intended for receiving "custom" binaries (like the present program) that can usually be run by any user.

Another possibility would be to install Atomsk in the /opt/bin directory, which is also reserved for custom packages and binaries. This can be done by modifying the `INSTPATH` variable in the `Makefile` before using the "`make install`" command.

If you are unsure about the best option for your system, just use the default setup or ask your local system administrator.

### Development

- How many lines of code does the program count?

As of version Beta 0.12 Atomsk counts about 52,000 lines of code, and about 27,000 lines of comments, dispatched in about 160 source files.

- Will a graphical user interface (GUI) be added?

Some users feel more comfortable with fancy windows and popping menus, instead of an unfriendly terminal. They will be very disappointed by Atomsk. This code is designed to be used as a command-line tool, which means that it must be lean and fast, run on remote machines, and be called in bash scripts. It is difficult to fulfill these scopes with a GUI. So the short answer is no: it is not intended that Atomsk will ever run through a GUI. If you do not like command-line and are looking for a user-friendly GUI, then Atomsk is probably not what you are looking for.

- Can you add the support for the format X / Can you add option X?

If I need it or if I am in a really good mood I will add the support for new file formats and new transformations. However if you need something peculiar you will probably get it faster if you program it yourself. Check the information for developers.

- Why is that program written in bloody Fortran and not Python/C/C++/Java/<your favorite language here>?!?

Primarily, because Fortran is the language I know best. And a posteriori I don't regret it: Fortran can natively handle complex numbers very easily, and utilize LAPACK (a library also written in Fortran) very simply. However, since Atomsk is libre software, it is part of your rights to re-code it in your favorite language if you are willing to.

Back to main menu