Install From Source

Installation on MacOS

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

MacOS users must install Xcode to compile the program. Since C++11 support is necessary, Xcode 8 or later is needed.

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 Xcode can be installed from its website. 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, e.g., Homebrew and MacPorts. For instance, the following command will install the listed packages from Homebrew:

brew install git cmake qt@5 qwt-qt5 eigen libssh

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.app/ directory. You can run the XtalOpt in various ways. For example, if you're in the build directory:
(1) GUI mode: run "open ./bin/xtalopt.app" or "./bin/xtalopt.app/Contents/MacOS/xtalopt" command in terminal; or click on the "xtalopt.app" in the Finder app,
(2) CLI mode: run "./bin/xtalopt.app/Contents/MacOS/xtalopt --cli" in terminal.

Installing XtalOpt

Before proceeding to read this section, note that apparently MacOS will prevent all installed packages from running unless they are signed by a valid certificate. For more information about code-signing, start from here.

Although you can run the compiled program, you might want to install it to have a standalone package (in which the XtalOpt executable and required libraries are properly collected) to place it in you "Application" directory for easy access. 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/" 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 access). After installation, you will find the XtalOpt package in the installation location. Before running the installed program, consider the code-signing (noted above).

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

In the reference system, the required dependencies were installed using the Homebrew package manager. The following script was run in terminal, inside the build directory (located in the root of the XtalOpt source-code):

#!/bin/bash

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

qt5dir=/opt/homebrew/opt/qt5
qwtdir=/opt/homebrew/opt/qwt-qt5
libssh=/opt/homebrew/opt/libssh

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

cmake -DCMAKE_PREFIX_PATH=$qt5dir/lib/cmake/Qt5 \
      -DQWT_LIBRARY=$qwtdir/lib/qwt.framework/qwt \
      -DQWT_INCLUDE_DIR=$qwtdir/lib/qwt.framework/Headers \
      -DLIBSSH_INCLUDE_DIRS=$libssh/include \
      -DLIBSSH_LIBRARIES=$libssh/lib/libssh.dylib \
      ..

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

make -j3

This script compiles the XtalOpt code. If you desire to install it, you should adjust the script according to above comments about the installation.

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.