Back to main menu

## Compatibility

Atomsk is designed to run in Unix/Linux and Microsoft® Windows® environments.

## Availability

It is recommended to download Atomsk from the official Web site: https://atomsk.univ-lille.fr/

You may, at your convenience, download the executable binary for your platform, or download the source code and compile it for your system.

## Executable version

The easiest way to start with Atomsk is to download the executable version for your platform from this page. This static binary version should run out-of-the-box, without any additional requirement.

The GNU/Linux versions of Atomsk come with an install script called "install.sh". If you choose to run this script, run it as root (or with sudo). The program will be installed in /usr/local/bin/ by default.

## Compilation from source

If you do not wish to use the static binary version of Atomsk, you can download the source code and compile it yourself. The compilation requires the LAPACK library to be present on your system.

The source code of the program comes with a Makefile. For a summary of available targets, enter the `src` directory and type "`make`" or "`make help`". To compile the program, type:

`make atomsk`

If your machine has multiple CPUs or a multi-core CPU then it is possible to speed up the process with parallel compilation thanks to the `--jobs` (or `-j`) trigger. For instance, to compile the program using five threads:

`make -j5 atomsk`

Note that if the number of threads is higher than the actual number of CPUs on your machine then the compilation will not be faster.

If the command above does not work straightforwardly check the following points. First you need the GNU Make program installed on your computer. Second, by default the Makefile uses the GNU Fortran Compiler (`gfortran`), so it is recommended that you have it installed.

Then, check that the LAPACK library is installed on your system. The path to the library must be defined in the `LAPACK` variable. On UNIX/Linux systems, if LAPACK is installed system-wide then using "`LAPACK=-llapack`" should work. Otherwise (e.g. if you compiled LAPACK in your home directory), enter the full path to the library with the format: "`LAPACK=-L/path/to/library -llapack`". The users of Intel® MKL may refer to the Intel® documentation. On Microsoft® Windows® systems, a version of the LAPACK library properly compiled is also required (the `Makefile.windows` gives some hints on how to achieve that, see also here and/or here). Please note that the author of Atomsk will not provide any support for LAPACK. If you experience problems with getting or compiling LAPACK on your machine, please turn to the LAPACK community.

In order to customize the compilation for your machine, please do not edit the main Makefile (i.e. the file `Makefile`). Instead, it is recommended to create a separate file named `Makefile.something` that you can re-use each time you compile Atomsk. This custom `Makefile.something` may contain some or all of the following variables:

- `export` (this keyword is mandatory)
- `FORTRAN=mycompiler` indicates to use the compiler "`mycompiler`"
- compiler flags can be given with `FFLAGS=-my -flags`
- `LAPACK=/you/path/to/lapack/library`
- the installation paths `INSTPATH`, `BINPATH`, `DOCPATH`, `MPATH` can be specified. If only `INSTPATH` is given then the other paths will be defined relatively to it.
- the mention "`include Makefile`" is mandatory and must appear at the end.

You may take example on the provided alternatives `Makefile.g95`, `Makefile.ifort`, or `Makefile.local`. Then, to compile the code using your custom Makefile type:

`make -f Makefile.something atomsk`

Note that the program uses some procedures that are available only in Fortran 95, so make sure to use a F95-compiler. So far the program was tested and compiles successfully with the following compilers:

GNU/Linux:

- GNU Fortran (gfortran) version 9 or greater
- Intel® Fortran (ifort) 12.0, 13.0, 14.0

Microsoft® Windows®:

- MinGW-gfortran 1.0

In order to optimize the program you may also change the compilation flags, depending on your machine's architecture, by modifying the `FFLAGS` variable. Note that `-O3` can introduce very aggressive optimizations that can compromise the behavior of the code, a maximum optimization level `-O2` is recommended. When compiling on Microsoft® Windows® systems the compilation flag `-DWINDOWS` is required.

The default Makefile enables OpenMP, which means that some parts of the code can run in parallel on multiple cores. For OpenMP support to be enabled, the Makefile must contain the line "`OPENMP=-DOPENMP -openmp`". The last keyword "`-openmp`" enables OpenMP for GNU Fortran compiler, and must be replaced by the appropriate keyword if another compiler is used. To disable OpenMP, just comment that line.

If compilation results in errors, first have a look at the FAQ, and second ask your local system administrator to help you. If you believe that the problem is directly related to the source code of the program, then you can send a bug report to the author. Please be sure to specify which module caused a compilation error.

When successfull the compilation will result in an executable binary named "atomsk" under UNIX/Linux and macOS systems, or "`atomsk.exe`" under Microsoft® Windows®. You may copy this executable in a folder of your choice in order to run it.

The `Makefile` contains facilities to install the program system-wide on Linux machines (see below).

## Installation on Linux machines

Once the compilation is achieved, if you have the super user rights on your machine you can type:

`make install`

By default the program Atomsk will be copied into your /usr/local/bin folder, so that all users of your machine have access to it. The companion tools will also be copied to that folder and made executable. The present html documentation will be copied to the /usr/local/share/doc/atomsk folder (copy this location into a web browser to visualize it). The man page of Atomsk will be copied to /usr/local/share/man/man1/ and can be accessed by typing "`man atomsk`". These default directories can be changed by editing the Makefile and changing the `INSTPATH`, `DOCPATH` and `MANPATH` variables.

You can also use the command "`make all`" with superuser rights to compile and install the program in one shot (this is equivalent to "`make atomsk && make install && make clean`").

If you don't have the superuser permissions on your machine, then either run the program by calling it with its full absolute path; add the path to the program in your `PATH` environment variable; or create an alias.

## Uninstallation on Linux machines

If you installed the program with the `make install` command, then you may uninstall it by entering the `src` directory and typing with super-user rights:

`make uninstall`

This will remove the file atomsk as well as the documentation from their respective paths (see the Install section above).

If you did not install the program with the `make install` command, simply remove the whole atomsk folder from your disk. If relevant, also remove the associated path from your `PATH` environment variable and/or the alias(es).

## Create an archive

You can easily create a tarball archive of the program by entering the src directory and typing:

`make tar`

By default the archive will be placed in the parent folder.

Back to main menu