Install From Source

Installation on Linux

Obtaining the source code

To obtain the source-code of the latest stable version (or previous releases) of XtalOpt see the download page.

Compiler and dependencies

A C++ compiler with C++11 support is necessary to compile the program, e.g., GCC (version 4.8.4 or later) and Clang (version 3.5 or later).

Moreover, compiling XtalOpt requires the following dependencies:

(1) git (any version),
(2) cmake (any version)
(3) Qt framework (version 5.2.1 or later of Qt5),
(4) Qwt libraries (version 6.1.3 or later, and compiled with the same version of the installed Qt),
(5) Eigen library (version 3 or later),
(6) libssh and openssh (this is not required if you disable the ssh; which is enabled by default).

The compiler and required dependencies can be downloaded and installed from their websites (sometimes that requires compiling them from source). However, they are most easily installed using package managers available on most linux distributions. For example, on Ubuntu linux, the GCC compiler can be installed with:

sudo apt install build-essential

and dependencies can be installed by the following command in terminal:

sudo apt install git cmake qtbase5-dev libqwt-qt5-dev libeigen3-dev libssh-dev

Note that the package names or syntax might change as the package managers and their content evolve and update over time!

Configuring the build

Once all required packages are installed, the user should create a "build" directory in the root of the XtalOpt source-code directory. In the "build" directory, then one can configure the build using

cmake ..

If the dependencies are installed in standard locations or available through environment variables, there is a chance that cmake will find them (or at least some of them!). If the configuration fails, however, you may inspect the output of the cmake command to see what are the missing libraries/packages. You need to redo the build with providing the correct path to required dependencies using the appropriate configuration flags:

cmake .. [-D<flag1>=<value1> -D<flag2>=<value2> ...]

To our experience, those which are most likely to be a source of trouble (along with their corresponding cmake flags) are as follows:

Compiling XtalOpt

After configuring the build, you can compile the code with the "make" command (or, "make -jN" for parallel compilation using "N" processes).

Upon successful compilation, there should be a directory named "bin" in the build directory which contains the xtalopt executable file. You can run the XtalOpt in various ways. For example, if you're in the build directory:
(1) GUI mode: run the "./bin/xtalopt" command in terminal,
(2) CLI mode: run the "./bin/xtalopt --cli" command in terminal.

Installing XtalOpt

Although you can run the compiled program, you might want to install it to have a standalone installation directory (in which the XtalOpt executable and required libraries are properly collected). In order to configure the code for installation, you should add the "-DBUILD_INDEPENDENT_PACKAGE=ON" flag to the cmake command.

Note that the default installation location is the "$HOME/bin/" directory. Alternatively, you can specify another location by adding the "-DCMAKE_INSTALL_PREFIX=<desired/path/for/installation>" flag to the cmake command.

Finally, after compiling the code with the above installation-related cmake flags, you need to run "make install" (or, "sudo make install" if the specified installation directory requires root privileges). After installation, you will find the XtalOpt package in the installation location.

Example of a complete build script

The details of the cmake and make setup would depend on the compiler and the installed dependencies. With that in mind, we are providing the following bash script just as an example of a possible setup to build the code on Linux.

In the reference system, the required dependencies were installed using using the above-mentioned "apt" utility. Then, the following script was run in terminal, inside the build directory (located in the root of the XtalOpt source-code), to install the compiled code in the "xtalopt_linux" directory in the root directory of XtalOpt source-code:

#!/bin/bash

# *********************************************************
# **** Set all variables to their correct directories  ****
# *********************************************************

insdir=$PWD/../xtalopt_linux

# *********************************************************
# **** Configure the build                             ****
# *********************************************************

cmake -DBUILD_INDEPENDENT_PACKAGE=ON \
      -DCMAKE_INSTALL_PREFIX=$insdir \
      ..

# *********************************************************
# **** Compile XtalOpt                                 ****
# *********************************************************

make -j3

# *********************************************************
# **** Install XtalOpt                                 ****
# *********************************************************

make install

To SSH or not to SSH?!

By default, XtalOpt is ssh-enabled to facilitate a remote server access. That's, to let you running XtalOpt on your personal computer while the structure optimizations are performed on a remote server. If you don't need this option and plan to use the code only on your computer, then the ssh feature can be disabled by setting "-DENABLE_ssh=OFF" at the configuration time. In that case, all ssh-related configuration flags are irrelevant and can be removed, and XtalOpt build does not depend on libssh.

About Kerberos authentication

If you need to use Kerberos authentication to establish a ssh connection to the remote server, the libssh library used by XtalOpt will not work. There is a workaround for Unix-like system (Linux and possibly Mac) users, which will call the command line ssh/scp commands to communicate with the remote cluster. This can be utilized by adding -DUSE_CLI_SSH=ON to the cmake command above, while the ssh is enabled in the build. This ssh backend will not prompt for a password, and expects the ssh commands to "just work". Passwordless ssh logins can be enabled using the ssh-copy-id command.