Legacy building system for 4.1.5 or below.

Note

This is a legacy version of the build system, which is based on the arch.make file for configuration options. This method has been removed in SIESTA 5, which relies on CMake; the following how-to is only kept as reference.

In this section, we describe how to compile SIESTA within a working build environment. We thus assume that you have already completed the steps explained in Preparing the environment.

There are 5 steps involved in the manual building of SIESTA:

  • Download and uncompress the source code.

  • Configure the build.

  • Compile the main executable.

  • Compile the utilities.

  • Run the test suite.

We walk through them in the following subsections.

Downloading the source distribution

Source tarballs of SIESTA can be downloaded for most versions from the official SIESTA releases on Gitlab. You can either download them from the website or through the command line. If you choose the website, the best is to use the files listed under the “Packages” section of each release. From the command line, if you want e.g. to get SIESTA 4.1.5, that would read:

wget https://gitlab.com/siesta-project/siesta/-/releases/v4.1.5/downloads/siesta-4.1.5.tar.gz

Once you have the tarball on your computer, you can follow the rest of the procedure from a terminal. The next step is to uncompress the downloaded tarball, e.g.:

tar xvzf siesta-4.1.5.tar.gz
cd siesta-4.1.5

Once done, you can configure the build.

Configuring the build

The source tree has to be prepared before compiling SIESTA. This basically means:

  1. Go to the Obj/ subdirectory or create a build directory.

  2. Create an arch.make file.

  3. Run the obj_setup.sh script.

  4. Check that the configuration is valid.

Section “2. Compilation” of the SIESTA User Manual describes these steps for different versions of SIESTA, with specific instructions for each of them. Here we will provide a summary with examples.

The first step is to use a build directory, which is a good practice because it protects the source files from being changed during the build. Unless you want to produce various SIESTA executables with different configurations from the same source tree, the recommended location is the Obj/ subdirectory. In the case of SIESTA, this step is mandatory, since compiling from the Src/ directory is explicitly prohibited.

Creating an arch.make in the Obj/ subdirectory is precisely what will make the configuration of the build different from another. This file contains all the parameters we have enumerated previously in Preparing the environment . Its structure varies between SIESTA versions, which is why we refer you to the SIESTA Usr Manual for details about what to tune in your arch.make file. If you do not know where to start from, you can use one the template provided by the DOCUMENTED-template.make file in Obj/.

Before compiling SIESTA, you have to make the information about the source tree available within the build directory. This is done by running the obj_setup.sh script, which is found in the Src/ subdirectory. When run from Obj/, the command is:

sh ../Src/obj_setup.sh

Note

If you run it from a different build directory, the path to this script might be different.

Last but not least, it is always a good idea to check that the configuration is valid by running make clean first. If this command is successful, you know that everything is ready for the build. In addition, you make sure that any artifact from a previous build is properly removed.

Taking back the example of SIESTA 4.1.5 from the previous subsection, the configuration of the build would like like the following:

cd Obj
cp DOCUMENTED-template.make arch.make
$EDITOR arch.make
sh ../Src/obj_setup.sh
make clean

where you replace $EDITOR by your preferred text file editor, e.g. emacs, nano or vim.

Compiling SIESTA

The slow and robust solution to compile SIESTA is to type make. If you have configured the build correctly, this will work with any version of SIESTA. After a few minutes, you should find a siesta executable in the build directory.

However, if you have SIESTA 4.1 or a more recent version, you can also compile the source code faster, through make -j N, where N is the maximum number of files to compile at the same time. A good number is anything between 2 and the number of cores of your CPU. If in doubt, try make -j 4, which works in almost any recent computer.

Note

If you get an error when compiling with make -j N, run make again without arguments to find out where the error occurred.

Once done, you can check that the SIESTA executable has actually been generated by typing ls -ltr. The last file in the list should be named siesta.

Compiling the SIESTA utilities

In the build directory, after configuring the build, you will find a subdirectory named Util/. If you go there, you will be able to build various pre- and post-processing tools that might help you with your SIESTA calculations. To see the full list, type:

cd Util
ls

For more details about these utilities, you can consult the README file there.

If you want to build them all, you can use the build_all.sh script:

./build_all.sh

However, since it can take some time, and since you might not need all of them, you can also build a few utilities one by one. For instance, if you want to build the gnubands utility to plot band structures with Gnuplot, you would type:

cd Bands
make clean
make
ls -ltr

After that, if you want to build denchar, you would type:

cd ../Denchar/Src
make clean
make
ls -ltr

You’re now done with building executables.

Installing and running executables

In this section, we will assume that you have successfully built SIESTA, as well as the utilities you need. If this not the case, yet, you can do it by following the instructions in one of the related sections:

As a starting point, we will suppose that you have just built the siesta, gnubands and denchar executables from SIESTA 4.1.5 and that they are still in your build directory, located at $HOME/src/siesta-4.1.5/Obj/.

Preparing an installation directory

One thing is to build software, another is to use it reliably. For the latter, we have to decide where we want to store what we have built. Here we will provide an example of good practice that we invite you to tune to best suit your own needs.

In this example, we have chosen to install all files related to SIESTA in a $HOME/siesta directory. Inside, we first have to create a basic structure, so that we can build and install several versions of SIESTA at the same time. Starting with our example, we would type:

mkdir -p $HOME/siesta/4.1.5/bin

As you can see, we are organising files by version (4.1.5) and by type (bin). Feel free to adapt this structure to your preferences. The most important aspect is to make a choice and stay consistent with it over time.

Note

Documenting your choices is a very good practice. A simple way to do it is to create a README file in the siesta/ directory and summarise there how you install files in its subdirectories.

For the moment, even though we are only installing executables, we will store them in a bin/ subdirectory, so that we don’t have to change our directory structure when we install other kinds of files, e.g. libraries or data files.

Copying the files to the installation location

In our example, we have built executables from the $HOME/src/siesta-4.1.5/Obj/ build directory. To make them available in a permanent way and free the space for new builds, we just have to copy the executables to our installation directory. In this case, we type:

cp $HOME/src/siesta-4.1.5/Obj/siesta $HOME/siesta/4.1.5/bin
cp $HOME/src/siesta-4.1.5/Obj/Util/Bands/gnubands $HOME/siesta/4.1.5/bin
cp $HOME/src/siesta-4.1.5/Obj/Util/Denchar/Src/denchar $HOME/siesta/4.1.5/bin

From now on, we can safely run make clean in the build directory without loosing the fruit of our efforts.

Saving the arch.make that was used to build teh executables is usually a good idea if we want to keep track of how we have built them. In this case, we can create a conf/ subdirectory where we will store them. In the process, it might also be useful to rename the arch.make to reflect our configuration choices explicitly. If we have built a SIESTA executable with GCC, OpenMPI and the Netlib linear algebra libraries, we can rename the file accordingly:

mkdir -p $HOME/siesta/4.1.5/conf
cp $HOME/src/siesta-4.1.5/Obj/arch.make \
    $HOME/siesta/4.1.5/conf/gcc-openmpi-netlib.make

Now, if we want to build different flavours of the same SIESTA version using different arch.make files, we could also rename the SIESTA executable following the same conventions:

mv $HOME/siesta/4.1.5/bin/siesta \
    $HOME/siesta/4.1.5/bin/siesta-gcc-openmpi-netlib

In this case, it would be advisable to update the $HOME/siesta/README file to keep track of these conventions.

Accessing the executables

One important step before being able to run the executables reliably is to update the environment variables. Two of them are of special importance:

  • LD_LIBRARY_PATH for the libraries.

  • PATH for the executables.

A good practice is to group these settings in a shell script that will be sourced whenever you want to run a specific version of SIESTA.

The first thing to decide is where to store the script. The most common used options are:

  1. Store the script in the version-specific installation subdirectory, in which case a single name can be used for all the instances of the script. In our example, this would be $HOME/siesta/4.1.5/siesta-vars.sh. If, in the future, we install SIESTA 5.0.0, the corresponding script would be $HOME/siesta/5.0.0/siesta-vars.sh.

  2. Store all the scripts in the same directory, e.g. $HOME/siesta/env/, in which case they would have to be named differently. In the above example, this would be $HOME/siesta/env/siesta-4.1.5-vars.sh and $HOME/siesta/env/siesta-5.0.0-vars.sh.

No solution is better than the other. What is important is that you feel at ease with it.

In the following, we will illustrate option 1. Adapting the instructions to option 2 is relatively easy. For SIESTA 4.1.5, the $HOME/siesta/4.1.5/siesta-vars.sh script will look like the following:

#!/bin/sh

PATH="$HOME/siesta/4.1.5/bin:$PATH"
export PATH

This is a minimalistic content. If your are familiar with shell scripting, you can of course refine on this.

From SIESTA 5.x on, as well as for the MaX-* releases, you have to install dependencies before compiling SIESTA. In this case, the recommended installation directory for e.g. SIESTA 5.0.0 would be $HOME/siesta/5.0.0/lib/ and the environment script would look like the following:

#!/bin/sh

LD_LIBRARY_PATH="$HOME/siesta/5.0.0/lib:$LD_LIBRARY_PATH"
export LD_LIBRARY_PATH

PATH="$HOME/siesta/5.0.0/bin:$PATH"
export PATH

Once the environment is correctly prepared, the SIESTA executables can be run in all kinds of circumstances in a reliable way.

Running the executables

Whenever you want to run a SIESTA executable you have installed as recommended here, you will have to source the corresponding script once per terminal session. For instance, if you want to run SIESTA 4.1.5, you will open a new terminal and type the following:

source $HOME/siesta/4.1.5/siesta-vars.sh

From that moment on, you can run SIESTA and its utilities by typing their names. If you want to understand better what is happening to the environment, you can start a terminal session and type which siesta, then source the script and type which siesta again. Your terminal will look like this:

$ which siesta
$ source $HOME/siesta/4.1.5/siesta-vars.sh
$ which siesta
$HOME/siesta/4.1.5/bin/siesta

The which command tells you which executable is actually run when you type the corresponding command. The first time, the SIESTA command is not available in the environment, hence which returns nothing. However, after sourcing the script, the environment has been updated and the command is available.

Note

It is always a good idea to check commands with which when you install software, no matter the method you use to install it.

These instructions are also valid when you run SIESTA through a batch scheduler on a HPC cluster. In this case, your batch job would look like the following:

#!/bin/bash
#PBS -q dft
#PBS -l nodes=1:ppn=12
#PBS -V
#PBS -N "Test"

# Set environment
source $HOME/siesta/4.1.5/siesta-vars.sh
which siesta

# Run SIESTA
cd my_job_dir
mpirun -np 12 siesta <my_input.fdf >my_output.log

One last important piece of advice: it is essential to avoid mixing the environments for different versions of SIESTA within the same shell session, as the results are highly impredictable and will likely end up in random crashes or garbled SIESTA output. If you want to run different versions of SIESTA, always prefer running them in different terminal sessions.

You’re now done. Enjoy your shiny new SIESTA installation!