Installing tensor-LEED dependencies

Tensor-LEED source code

The viperleed.calc package acts as a wrapper and feature extension to the TensErLEED package. It requires TensErLEED source files to be present on your machine. You can obtain all the necessary source code from the viperleed-tensorleed GitHub repository. We suggest downloading the most recent release into a local directory of your choice. Note that you may need to decompress the TensErLEED source files after downloading. See also Listing 1 for the expected folder structure.

If you want to use older version of TensErLEED, you can also download older releases from the releases tab of the viperleed-tensorleed repository. You can have multiple versions of TensErLEED on your system at the same time. viperleed.calc will use the most recent one by default. To select a different version you can use the TL_VERSION parameter.

When using multiple tensor-LEED versions, the folder containing the tensor-LEED code is expected to have the structure in Listing 1. The name of the top-level folder is up to the user (my_tensorleed in Listing 1). However, folder names for the TensErLEED source code should be named TensErLEED-v1.X.Y (or TensErLEED-v1.XY) for versions earlier than v2.0.0 (see parameter TL_VERSION for more details). The folder name for later versions is only required to begin with TensErLEED. The top-level folder (my_tensorleed in Listing 1) is expected to contain the compiled version of the EEASiSSS source code, obtained as described in Compiling static files.

Listing 1 Expected structure of the directory containing the tensor-LEED source code.
my_tensorleed/
├── eeasisss_src/       <-- EEASiSSS source code, compiled with make
│   └── ...
├── TensErLEED-v2.0.0/
│   ├── src/
│   │    ├── ref-calc.f
│   │    └── ...
│   └── lib/
│        ├── lib.tleed.f
│        └── ...
├── TensErLEED-v1.7.3/  <-- optional older release
│   ├── random_.c
│   ├── Makefile        <-- For random_.c, versions < v.1.7.4 only
│   └── ...
⋮
└── Makefile            <-- For EEASiSSS

viperleed.calc will need to know where the tensor-LEED code is located on your machine. You can either specify this each time you run viperleed.calc via command-line arguments or you can define the VIPERLEED_TENSORLEED environment variable. See Setting an environment variable for more details. With reference to Listing 1, the VIPERLEED_TENSORLEED environment variable (or the command-line argument) can equivalently point to either my_tensorleed or to any of its TensErLEED* subfolders.

Setting an environment variable

In this section we briefly describe how an environment variable is set on various platforms. The following examples are for the VIPERLEED_TENSORLEED environment variable that viperleed.calc can use to locate the tensor-LEED code.

You can set an environment variable via

export VIPERLEED_TENSORLEED="<path/to/your/local/copy/of/viperleed-tensorleed>"

The above will only set the VIPERLEED_TENSORLEED environment variable for the current session of the shell. To make the changes permanent, you can add the export statement, e.g., to your ~/.bashrc, via

echo '# Set environment variable for viperleed-tensorleed' > ~/.bashrc
echo 'export VIPERLEED_TENSORLEED="<path/to/your/local/copy/of/viperleed-tensorleed>"' > ~/.bashrc

Execute

setx VIPERLEED_TENSORLEED "<path/to/your/local/copy/of/viperleed-tensorleed"

in a CMD terminal. You then may need to reboot your system. Notice the use of setx rather than set: the latter only sets the VIPERLEED_TENSORLEED environment variable for the active session.

Open up the Windows Run dialog (shortcut Win+R), type sysdm.cpl, then press Enter to open the System Properties editor. Navigate to the Advanced tab, and click the Environment Variables… button. In the User variables for <user name> section, click New…. Use VIPERLEED_TENSORLEED as the Variable name. For Variable value use the full path to the folder containing the archives you have downloaded from the viperleed-tensorleed GitHub page. You may need to reboot your system.

Fortran compilers

viperleed.calc needs to compile the TensErLEED source code at run-time. This requires the presence of a suitable Fortran 77 & 90 compiler on the system. Unlike the original version of TensErLEED by Blum and Heinz [6], all TensErLEED versions supported by viperleed.calc (TensErLEED ≥ 1.6) also require BLAS and LAPACK libraries to be available. viperleed.calc supports gfortran from the GNU Compiler Collection (gcc) and the Intel Fortran compiler ifort without additional configuration. You can set the FORTRAN_COMP parameter to use any other Fortran compiler installed on your system. viperleed.calc will default to using ifort if available. Use the parameter FORTRAN_COMP to adjust this behavior.

The structure-search section, which is usually the computationally most expensive part of ViPErLEED and TensErLEED, supports parallelized compilation and execution with MPI. To use the MPI version of TensErLEED, you need to install an MPI implementation as well as the MPI compiler corresponding to your Fortran compiler. We recommend using Open MPI on Linux and macOS. The MPI compiler for gfortran is mpifort, for ifort it is mpiifort.

If you are running viperleed.calc on an HPC system, appropriate Fortran compilers and a preferred MPI implementation are likely already installed. For details regarding their usage, consult the documentation for your HPC system as well as its administrators.

viperleed.calc can run on Linux, macOS and Microsoft Windows, but the installation of the compilers differs significantly for each system.

Note

  • If you are running on an system based on an Intel processor, we recommend using ifort. It is known from experience to give better performance for TensErLEED.

  • Using the MPI version of TensErLEED is not strictly required, but highly recommended. Execution of the structure search may take significantly longer without MPI. A working MPI implementation is necessary to make use of multi-processing in the structure-search section, even if you are working on a single node.

ifort and mpiifort

This section provides a guide on how to install the Intel Fortran compiler ifort, an MPI implementation, and the ifort MPI compiler mpiifort. All the necessary components are packaged as part of the Intel oneAPI® toolkits.

ViPErLEED requires the Intel oneAPI® Base Toolkit and the Intel oneAPI® HPC Toolkit.

Note

The toolkits are multiple gigabytes in size and will take a while to download and install.

The BLAS and LAPACK libraries are packaged in the Intel oneAPI® Math Kernel Library (MKL), which is part of the Intel oneAPI® Base Toolkit. The Intel oneAPI® HPC Toolkit contains the Fortran compilers as well as an MPI implementation.

The full documentation of the Intel oneAPI® is available from the Intel website.

Installation of the Intel compilers and of the MPI implementation for Linux can be performed using a few shell commands. In this manual, we use apt, the standard package manager for Debian-based distributions. For installation instructions with other package managers see the guides by Intel.

As a first step, update the package index:

sudo apt update && sudo apt upgrade

After adding the Intel oneAPI® repository following the instructions by Intel, install the required packages:

sudo apt install intel-basekit -y
sudo apt install intel-hpckit -y

Once installation completes, we need to configure the system and add the compilers to our system path. First, we need to make sure the required build tools (e.g., cmake) are present:

sudo apt install cmake pkg-config build-essential -y

Then, we configure the Intel oneAPI® installation such that it is discovered by our environment. For this, we need to source the correct *vars.sh file that sets the required CLI arguments. We recommend you do this by adding the following line to the end of the startup script of your shell (usually ~/.bashrc):

source <full/path/to/intel/oneapi/shell/script>

Follow this guide by Intel to determine the correct shell script for your release version.

Afterwards, the required compilers should be available for use. You can check whether ifort is present by using

which ifort

If the result is a path, it means that the shell knows the compiler exists. You can do the same check with mpirun and mpiifort to check that they are properly configured as well.

Warning

Newer Macs using “Apple Silicon” ARM-based chips are incompatible with the Intel compilers (since they don’t use Intel chips). Use gfortran and mpifort instead.

Follow the Intel guide to install the Intel oneAPI® toolkits under macOS. As for Linux, you will need to install the Intel oneAPI® Base Toolkit and the Intel oneAPI® HPC Toolkit.

For information on installing WSL see this section. Start WSL by typing

wsl

in your terminal, then follow the same instructions as in the Linux section.

Warning

To run viperleed.calc and TensErLEED under Windows, we recommend using the Windows Subsystem for Linux (WSL, available starting from Windows 10). Running natively on Windows is possible, but experimental and not recommended.

Warning

The structure-optimization section currently contains Python code that is incompatible with Windows. Therefore, a full LEED-I(V) calculation cannot be performed under Windows.

Follow the Intel guide to install the Intel oneAPI® toolkits under Windows. As for Linux, you will need to install the Intel oneAPI® Base Toolkit and the Intel oneAPI® HPC Toolkit.

The Intel oneAPI® toolkits require specific environment variables to be set before compilers can be used. The toolkits come with dedicated .bat scripts that must be executed on each session of the terminal. For more information concerning which script to use, see this guide from Intel.

Notice that cmd can use a mechanism similar to the .bashrc startup script for Linux’s bash. This means that dedicated commands can be executed upon startup of each cmd session. To set this up:

  • Open the Windows registry editor via the Run dialog (Win+R): type regedit, then press Enter. Confirm the administrator permissions.

  • Navigate to HKEY_CURRENT_USER/Software/Microsoft/Command Processor/. If Command Processor does not exist, right click on Microsoft, select New ‣ Key, and name the new entry Command Processor.

  • Find the AutoRun entry in the right panel. If no AutoRun exists, create a New ‣ String value by right clicking. Name it AutoRun.

  • Skip this passage if the AutoRun entry already has a value. Modify… the empty value of the AutoRun entry to %USERPROFILE%\cmd-autorun.bat. %USERPROFILE% is the path to your user directory. You can find its value by typing

    echo %USERPROFILE%

    in a terminal. On Windows 10 and later, you can also directly navigate to the location in Explorer by typing %USERPROFILE% in the Windows Start menu or in the address bar of an Explorer window.

  • Navigate to the file path set as a value for the AutoRun entry. You can create a new file with the correct name if it does not exist. Then append the following lines to the end:

    @echo off
call "<full/path/to/correct/intel/oneapi/bat/file>"
@echo on

  • Close the registry editor.

  • Open a new cmd session, and test that the Intel oneAPI® compilers are now visible via

    ifort --version
mpiifort --version

gfortran and mpifort

This section provides a simple guide on how to install the GNU Fortran compiler gfortran, the Open MPI implementation, and the gfortran MPI wrapper mpifort. See also the guide on the Fortran-language reference page for how to install gfortran on various operating systems.

First, using your package manager, update the package list and install the newest version of gfortran. In this manual, we use apt, the standard package manager for Debian-based distributions.[1]

sudo apt update
sudo apt install gfortran -y

The compiler can be invoked with the gfortran command. You can show the version and check whether gfortran was installed properly using

gfortran --version

In addition to gfortran, you also need to install the BLAS and LAPACK libraries. Use

sudo apt install libblas-dev liblapack-dev

Next, install Open MPI (or another MPI implementation of your choice) to make mpirun available:

sudo apt install openmpi-bin

Finally, install the gfortran MPI wrapper mpifort:

sudo apt install libopenmpi-dev

For running under macOS, it is recommended to first install a package manager such as brew. This will also install the XCode command-line tools which are required for installing most other components.

Using the brew command, you can then easily install gfortran and the Open MPI implementation (automatically including mpifort).

brew install gfortran
brew install open-mpi

There is no need to install BLAS and LAPACK, as macOS already ships with these libraries preinstalled.

Warning

If the XCode command-line tools are not installed before you install gfortran, you will get an error stating that the -lSystem library is not available. If this happens, make sure to first install the XCode command-line tools via

xcode-select --install

and then reinstall gfortran with

brew reinstall gfortran

Install WSL as described in this section. Start WSL by typing

wsl

in your terminal, then follow the same instructions as for Linux.

Warning

To run viperleed.calc and TensErLEED under Windows, we recommend using the Windows Subsystem for Linux (WSL, available starting from Windows 10). Running natively on Windows is possible, but experimental and not recommended.

Warning

The structure-optimization section currently contains Python code that is incompatible with Windows. Therefore, a full LEED-I(V) calculation cannot be performed under Windows. For this reason, this section does not describe a way to obtain an MPI implementation nor an the mpirun Fortran compiler.

Warning

The notes below are for installing the very basic, non-optimized LAPACK/BLAS versions. Hence, execution of the code will be rather slow.

  • Install MSys2, which then installs MinGW, then open the MSys2 shell.

  • Update MSys2 running

    pacman -Syu

  • Install gfortran and other useful packages via

    pacman -S mingw-w64-x86_64-toolchain

  • Add the <path_to_mingw_installation>/mingw64/bin entry to your Path environment variable. This way, calling gfortran from the terminal will find the one just installed with no need to explicitly passing the whole path. See Setting an environment variable for how to access the environment-variable settings on Windows. Edit the Path environment variable by appending <path_to_mingw_installation>/mingw64/bin. On Windows 7, use a semicolon as separator.

  • Install developer tools, cmake, and git with

    pacman -S base-devel
pacman -S mingw-w64-x86_64-cmake
pacman -S git

  • Clone the LAPACK git repository with

    git clone https://github.com/msys2/MINGW-packages.git

    This is the basic, non-optimized version. There are ways to also build better versions. See here.

  • Move to the LAPACK directory with

    cd MINGW-packages/mingw-w64-lapack

  • Build LAPACK and BLAS packages with

    makepkg-mingw

    Should curl complain about some certificates, you can also download the LAPACK/BLAS source code as a .tar.gz archive. Take the version that curl complains about, and place the archive in the package folder, which you can find in <path_to_mingw_installation>/home/<user_name>/MINGW-packages/mingw-w64-lapack. This build will take quite a while.

  • Install LAPACK/BLAS packages with

    pacman -U mingw-w64-x86_64-lapack-<REPLACE_WITH_VERSION>.pkg.tar.zst

    Note that the archive may have a different suffix. Run ls in the same folder to check the correct name.

You can then test the LAPACK installation with

cd ~
wget http://www.math.ucla.edu/~wotaoyin/software/lapack_test.cpp  # download
g++ lapack_test.cpp -llapack -o lapack_test     # build
./lapack_test                                   # run

For actually running, set the FORTRAN_COMP parameter in the PARAMETERS file as follows:

# -std=legacy makes it work for Fortran77
FORTRAN_COMP = 'gfortran -O2 -std=legacy'
# NOTE: order of LAPACK and BLAS is important!
FORTRAN_COMP post = '-llapack -lblas -lpthread'

There is currently no solution for installing gcc compilers with LAPACK/BLAS on 32-bit Windows.

Compiling static files

In addition to the TensErLEED source code, which is compiled at run-time, ViPErLEED needs a few auxiliary programs that need compiling before a calculation can be started.

EEASiSSS

This is the “Elastic Electron–Atom Scattering in Solids and Surface Slabs” (EEASiSSS) program by Rundgren [11]. Its source code is distributed by the ViPErLEED developers in the viperleed-tensorleed GitHub repository with permission from the author. See also this section for more information on how to obtain the source code.

EEASiSSS is used by ViPErLEED during the Initialization section to generate the PHASESHIFTS file.

Install the Fortran compiler of your choice following these instructions. Then proceed to compilation from source as described in the following.

EEASiSSS can be compiled automatically using the provided Makefile. Navigate to your local version of the viperleed-tensorleed repository using

cd path/to/viperleed-tensorleed

From there, call either make intel or make gcc to compile using the Intel or GCC Fortran compilers, respectively.

EEASiSSS can be compiled automatically using the provided make.bat. Navigate to your local version of the viperleed-tensorleed repository using

cd "path\to\viperleed-tensorleed"

From there, call either make.bat intel or make.bat gcc to compile using the Intel or GCC Fortran compilers, respectively.

An alternative to compilation from source is using the precompiled eeasisss_windows.exe executable available in the viperleed-tensorleed repository. It should be renamed to eeasisss.exe after download.

Warning

The precompiled eeasisss_windows.exe executable was built on a machine that is likely different from yours. It may not work at all on your machine, or may produce unexpected results. It is safer to compile from source.

\(R\)-factor extension for ASE

For using the atomic simulation environment (ASE) with ViPErLEED, you may need to compile the \(R\)-factor extension for viperleed.calc. This extension is used to calculate the \(R\) factor in conjunction with the ASE package. It relies on F2PY, which is installed by default with NumPy.

To build the \(R\)-factor extension module, navigate to your local copy of the viperleed package in the terminal and call make in the extensions directory.

There are no automatic means to build the \(R\)-factor extension module on Windows. Native-Windows users must manually build the extension using F2PY. See the UNIX Makefile for build flags. You can find the Makefile in the extensions directory of your local copy of the viperleed package.

Random numbers library for TensErLEED < v1.7.4

Note

Users wishing to run natively on Windows can skip this step, as the random numbers are used only in the structure-optimization section, which is currently incompatible with native execution on Windows due to limitations on the Python code.

TensErLEED versions up to v1.7.3 need the C-object files called random_.o and MPIrandom_.o. These files must be precompiled with C and C MPI compilers, respectively. A Makefile is also provided for them. If you followed the instructions for obtaining the Fortran compilers, you should already have the necessary C compilers installed (from either GCC or Intel).

To compile the random-number generation library for a certain TensErLEED version, navigate in your terminal to the respective directory containing the TensErLEED source files and call either make intel or make gcc to compile them using the Intel or GCC C compilers, respectively.