Tips for ABINIT users and developers

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== External dependencies of Abinit ======

===== Minimum requirements =====

==== Hardware and system requirements ====

Abinit is able to run on a broad range of devices and operating systems. In order to build it and run it, you will need at least:
  * 1Gb of memory (RAM);
  * 4Gb of free disk space;
  * a Unix-compatible development environment;
  * recent C and Fortran 95/2003 compilers;
  * Python >= 2.5.

For seamless builds and fast tests, the recommended configuration is the following:
  * microprocessor with at least 4 cores;
  * at least 8Gb of memory (RAM);
  * at least 20Gb of free disk space;
  * Linux;
  * GNU Compilers Collection (GCC) >= 4.9 (4.8 will do, yet produce slower executables);
  * Python >= 2.7.5.

MacOSX users will usually be able to build Abinit after installing a few missing basic tools and a Fortran compiler, although the procedure is not always straightforward. Please consult [[http://forum.abinit.org/|the Abinit Forums]] if you encounter issues. Since MacOSX is not 100% Unix-compatible, we highly recommend you to check with extreme care that Abinit is behaving properly before running production calculations.

Windows users might be able to build Abinit after installing [[https://www.cygwin.com/|Cygwin]]. They will find guidance and example config files on [[http://forum.abinit.org/|the Abinit Forums]]. We recommend the use of Windows only for teaching and testing purposes, not for production calculations, due to the impossibility of checking whether the underlying proprietary software is performing as it should and because the opaque automatic updates might affect the accuracy of the calculations in a totally impredictible way.

==== Linear algebra ====

To be able to run, Abinit requires working linear algebra libraries compatible with [[http://www.netlib.org/blas/|BLAS]] and [[http://www.netlib.org/lapack/|LAPACK]]. Such libraries can be found or easily installed on any modern computer. They are always available on a supercomputer. If you do not know how to access them, it would be a good idea to ask your system administrator before building Abinit.

There are many implementations of BLAS and LAPACK available nowadays. If you are running a personal computer with Linux, look for packages such as:
  * //libatlas-dev//, //libblas-dev//, and //liblapack-dev//, for Debian-based distributions;
  * //atlas-devel//, //blas-devel//, and //lapack-devel//, for RPM-based distributions;
  * //atlas//, //blas//, and //lapack//, for other distributions.
Depending on your computer architecture and compilers, different packages may provide different levels of reliability and performance. In some cases, you may have to make some tests and benchmarks before selecting the implementation that best suits your needs. On Intel-based supercomputers, you will usually find the [[https://software.intel.com/en-us/intel-mkl|Math Kernel Library (MKL)]] installed with Intel compilers, a combination which provides the highest performance for most calculations but is not always the most stable one.

In any case, we highly recommend you to take good care of finding the adequate linear algebra libraries for your calculations before anything else, as it will have a significant influence on your user experience of Abinit. You can find more information about the linear algebra implementations supported by Abinit in the config file template available in the source tarball, at //~abinit/doc/build/config-template.ac//.

==== Fast Fourier Transforms (FFTs) ====

Abinit comes with built-in [[http://dx.doi.org/10.1016/S0010-4655(03)00287-X|FFTs from Stefan Goedecker]], which perform very well on a broad range of configurations. However, in some cases, the use of FFTW and/or MKL may provide better performance or become necessary. This is why Abinit offers the possible selection of the FFT routines that will be used for the calculations.

==== Optional features ====

The presence of different libraries and tools on your system will let you customize and enhance the capabilities of Abinit in three areas:
  * Input/Output (I/O), both for text files and binary data, with //ETSF_IO//, //FoX//, //Libpspio//, and //LibYAML//;
  * Mathematical operations, with //GSL//, and //Levmar//;
  * Density-Functional Theory (DFT), with //BigDFT//, //LibXC//, and //Wannier90//.
Although Abinit will be able to work in degraded mode without them, they might be mandatory for some of your calculations to run. LibXC is a typical example of such a dependency, since it lets you access a few hundreds of well-tested exchange-correlations functionals, while Abinit provides a very restricted set of them to perform basic tests.

==== Atomic data ====

Abinit requires atomic data to be able to run, mainly pseudopotentials and/or Projector-Augmented Waves (PAW) datasets, as well as atomic densities. Although the source tarball of Abinit contains some of them to run the test suite, they are not suitable for production calculations. Please remember to download the ones you need before running Abinit. They can be found on the Abinit website:
  * [[http://www.abinit.org/downloads/atomic-data-files]]

===== Preparing your build environment =====

If you wish to build some external packages before building Abinit, you might have to install more software prerequisites than just for Abinit, as well as to tune some environment variables and parameters of your system. Selecting adequate compilers is also a critical step. Please remember that, for every choice, the latest version is usually not the best one, as it very often lacks the testing and bugfixing that older and more robust versions have. If this is the first time you do this, take your time to do it well, because it will greatly improve and accelerate the build of the various packages you might need.

If you are a beginner, the bad news is that you will suffer a bit before succeeding in building Abinit. The good news with external dependencies is however that you will have to do it only once a year on average. Taking notes of everything you are doing to achieve the build of a package is a very clever idea and will save you a lot of time in your future attempts to build new versions of the same package. With practice, you will also understand better and better the underlying concepts and designs, which will let you navigate with ease in this apparently messy world.

If you are using a Debian-based Linux distribution, please note that installing the //science-nanoscale-physics-dev// metapackage will ensure that your development environment contains all the basic libraries and tools needed to build Abinit and its dependencies. For more details, please consult the Debian website:
  * [[http://blends.debian.org/science/tasks/nanoscale-physics]]
  * [[http://blends.debian.org/science/tasks/nanoscale-physics-dev]]

===== External libraries and tools =====

<WRAP important>**IMPORTANT NOTE**\\ We can only provide very limited support regarding external tools and libraries, since they are evolving independently of Abinit. If you encounter problems building them, it is much better for everybody that you directly contact their developers, since they will provide you with much better support than us and will receive bug reports from you that will help them improve their software.</WRAP>

==== Standard installation procedure ====

Each version of Abinit is compatible with only some versions of its external dependencies. To determine which version of each package you should download, please consult our [[build:extdeps-compat|compatibility matrix]]. Once downloaded, and unless specified otherwise in the package documentation, the standard procedure to build a package is to open a terminal and type the following commands:
<code>
tar xvzf <package>-<version>.tar.gz
cd <package>-<version>
./configure --prefix=/path/to/installation [options...]
make
make check
make install
export LD_LIBRARY_PATH="/path/to/installation/lib:${LD_LIBRARY_PATH}"
export PATH="/path/to/installation/bin:${PATH}"
export MANPATH="/path/to/installation/share/man:${MANPATH}"
</code>
When unpacking, the options given to //tar// may vary depending on the file extension. If the file ends in //.zip//, you will of course use //unzip// instead of //tar//. See the corresponding manual pages (//man tar// and //man unzip//) for more information.

Before building external packages, it is important that you choose where you will install them. This corresponds to the //--prefix// option of the configure script. The available choices you have highly depend on the privileges you have for the computer you are building Abinit on. You may of course organize them as you wish. We just wish to mention here 3 widely used ways of doing it.
  - Installing them all in one common prefix, in order to make it easier to find them. In this case, we recommend you to include //abinit-x.y.z// or //abinit/x.y.z// in the prefix path (e.g. ///opt/abinit-8.0.1/extdeps//, or //${HOME}/abinit/8.0.1/extdeps//), which will let you gather different versions of the external dependencies for different versions of Abinit without interferences.
  - Installing each of them in a separate directory, in order to play more easily with the different versions and make compatibility tests as well as benchmarks, e.g. //${HOME}/mylibs/libxc-2.2.1//. This option provides the highest flexibility, while being a bit more verbose when it comes to configure Abinit.
  - Grouping them by compiler vendor and version, if you find yourself in a situation where you have to build packages for different compilers. This explicit separation is often necessary because Fortran modules are unfortunately incompatible between compiler vendors and even many times between different versions of the same compiler too.
You may of course make any combination of the previous or define your own structure if it makes more sense to you. If you want to be time-efficient, always look for the solution that will minimize the number of builds.

When it comes to the build itself, do not hesitate to use //make -j// instead of //make// for packages that support parallel builds. You might gain an appreciable amount of time.

A good practice is to always run //make check// before //make install//, in order to run the test suite of the package after building it. Unfortunately, the quality and completeness of the tests vary a lot between packages. Sometimes, you may thus have to consult the websites and/or the developers of the packages to evaluate the seriousness of failing tests.

After installing a package, you have to tell the system and the compilers where to look for it, which is something most beginners forget about. This corresponds to the //export ...// commands in the case of a Bourne-compatible shell (you would use //setenv// for a C-compatible shell). Prepending the install library path to //LD_LIBRARY_PATH// has to be done almost systematically, as it will tell the compilers where to look for the new libraries. Be careful that, in some cases, the trailing directory is called //lib64// or //lib32// instead of //lib//. Prepending the install binary path to //PATH// will depend whether the package has executables. When it is the case, it is always time-saving to add the possible manual pages to the search path of the //man// command (type //man man// in a terminal if you do not know what we are talking about). If you wish to make the packages permanently accessible, we recommend you to store them in a config file of your shell (//~/.bash_profile// for Bash, //~/.profile// for Ksh, and //~/.login// for Csh/Tcsh). If you have chosen to install all packages within the same prefix, you will have only one export of each kind to perform. Otherwise, you will have to do the exports for each package, one after the other.

<WRAP tip>If you are managing many packages on a shared computer, it might be worth learning //Modules//. You will find all necessary information there: [[http://modules.sourceforge.net/]]</WRAP>

==== BigDFT: wavelets for low-dimensional systems ====

BigDFT is a wavelet-based DFT code developed by the [[http://inac.cea.fr/L_Sim/|L_Sim atomistic simulation laboratory]]. It might be interesting to you if you study large low-dimensional systems (surfaces, wires) with Abinit. You can download it from the following address:
  * http://bigdft.org/
If you are going to use BigDFT exclusively with Abinit, you may configure it with the following options to accelerate the build:
<code bash abinit-bigdft-config.sh>./configure --prefix=/install/path --enable-internal-libyaml --disable-shared --without-archives --disable-binaries --disable-bindings --enable-libbigdft</code>
Make sure that you enable the build of //libbbigdft// in any case, since Abinit requires it to enable its BigDFT-related features. Please also note that BigDFT depends on linear algebra libraries and LibXC (see below).

Please consult and/or report issues on the [[http://bugs.launchpad.net/bigdft|Launchpad BigDFT project page]].

==== ETSF_IO: platform-independent data exchange ====

ETSF_IO is a Fortran library implementing the [[http://www.etsf.eu/fileformats|ETSF file format]] for plaftform-independent data exchange between Density-Functional Theory-based software packages. If you plan to perform calculations involving more scientific codes than just Abinit, or know that you will use the same data on different computers, ETSF_IO is a library of choice. Since the file format specifications are fully open, you can read and write ETSF_IO data the way you prefer, either by using the ETSF_IO library or by developing your own routines to access the data.

ETSF_IO depends on NetCDF (Network Common Data Form) to ensure the platform-independence of the data. NetCDF is available on most supercomputers and from standard packages in all Linux distributions. On other platforms, it may sometimes be tricky to get NetCDF running properly. This is why we strongly advise you to consult the NetCDF website and the NetCDF developers for any question related to the build of NetCDF. They will help you way better than we could ourseleves. The NetCDF website contains comprehensive documentation about NetCDF and its components. It can be found there:
  * [[http://www.unidata.ucar.edu/software/netcdf/]]
Once you know a little bit about NetCDF, its complexity, and its dependencies, you will easily understand why we cannot provide support for it and why it is better for you to ask your system administrator to build it for you if you do not feel up to the task. If you plan to use NetCDF exclusively with Abinit, you can try to configure it with the following options:
<code bash abinit-netcdf-config.sh>./configure --prefix=/install/path --disable-cxx --disable-cxx-4 --disable-dap --disable-hdf4 --disable-netcdf4 --enable-fortran --enable-static --disable-shared</code>
It will work on most platforms, with however no guarantee. The [[http://www.unidata.ucar.edu/software/netcdf/#help|support section of the NetCDF website]] contains helpful information and instructions to solve many issues.

Once you have a running NetCDF installation, you can download ETSF_IO from Launchpad:
  * [[https://launchpad.net/etsf-io]]
If NetCDF has been installed in a non-standard directory, you will have to let the configure script of ETSF_IO know where to find it through its //--with-netcdf-incs// and //--with-netcdf-libs// options, e.g.:
<code bash abinit-etsf_io-config.sh>./configure --prefix=/install/path --with-netcdf-incs="-I/path/to/netcdf/include" --with-netcdf-libs="-L/path/to/netcdf/lib -lnetcdff -lnetcdf"</code>
Another important option is where ETSF_IO will install its Fortran modules. By default it will store them under //$prefix/include/fortran_compiler_vendor//, but you may wish to install them somewhere else for more convenience. In any case, you will have to remember where they are when you build Abinit.

==== FFTW: Fastest Fourier Transform in the West ====

Although Abinit has its own Fourier transform routines, FFTW is an optimized Fast Fourier Transform library which can provide an interesting speedup on some architectures and for some calculations. It is very widely available on all kinds of platforms, which means that you will likely not have to build it yourself. Should you need to do it, the FFTW website will provide you with all you need to build the library:
  * [[http://www.fftw.org/]]
A bit of caution, though: if you build FFTW yourself, the optimization flags you provide the compiler with will have a critical influence on the performance of the library, both in terms of speed and accuracy. We highly recommend you to run the test suite of FFTW before using it with Abinit and consult experts around you or on internet to adjust the compile flags in a safe and efficient manner.

==== FoX: XML I/O support ====

[[wp>XML|XML (eXtensible Markup Language)]] is an ubiquitous and standard way to handle text data. However, reading and writing XML files from Fortran is far from being straightforward. The FoX library thus provides a comprehensive set of helper routines to access and parse XML files directly in Fortran. Its primary uses in Abinit are:
  * the reading of PAW datasets;
  * the writing of XML output for post-processing.
Since FoX is used punctually and at very well defined moments during the calculations to access small files, optimization is not a concern at all. This makes it easier to build the library and debug potential issues.

FoX can be downloaded from the website of the University of Bristol:
  * [[http://www1.gly.bris.ac.uk/~walker/FoX/]]
If you plan to use FoX exclusively with Abinit, just know that Abinit only requires the SAX parser to work. You may thus configure FoX with the following options:
<code bash abinit-fox-config.sh>./configure --prefix=/install/path --enable-sax</code>
Issues should be reported to the GitHub bug tracker of FoX:
  * [[https://github.com/andreww/fox/issues]]

==== GSL: GNU Scientific Library for mathematical operations ====

GSL provides various mathematical routines to perform interpolation, integration, derivation, calculate special functions, and much more. It is currently used very little by Abinit as an optional replacement for intrinsics which are not present in some Fortran compilers.

GSL can be downloaded from the GNU website and all its mirrors:
  * [[https://www.gnu.org/software/gsl/]]
GSL does not require any particular tuning to work with Abinit. As it is a well-designed and portable project, the standard procedure described above should work seamlessly in most cases.

Should you encounter any issue while building GSL, please follow the guidance that you can find on the GSL webpage:
  * [[https://www.gnu.org/software/gsl/]]

==== Levmar: Levenberg-Marquardt algorithm for GW ====

When performing GW calculations, at the moment of calculating the screening, Levmar allows the fitting of a function in the complex plane pole-by-pole in such a way as to increasingly minimise the error, thanks to the use of the Levenberg-Marquardt algorithm.

Levmar is a C++ library which can be downloaded from there:
  * [[http://users.ics.forth.gr/~lourakis/levmar/]]
Although this library is relatively small and straightforward to build, you have to be prepared to do some manual adjustments on some architectures. And since its use is limited to particular kinds of GW calculations, you probably do not need it. Our advice: if you do not know what this is about, forget about Levmar.

Potential issues when building Levmar should be reported to:
  * [[mailto:lourakis@ics.forth.gr?subject=levmar|Manolis Lourakis]]

==== Libpspio: reading atomic data generated for other programs ====

Libpspio is a general-purpose library to read and write pseudopotential formats. It is part of the [[http://esl.cecam.org/|CECAM Electronic Structure Library]]. It allows Abinit to read pseudopotentials generated for other scientific codes. In the future, it will also read PAW datasets.

Libpspio can be downloaded from Launchpad:
  * [[https://launchpad.net/libpspio]]

Libpspio is a C library and does not build Fortran interfaces by default. If you plan to use it with Abinit, please configure it with //--enable-fortran//, e.g.:
<code bash abinit-libpspio-config.sh>./configure --prefix=/install/path --enable-fortran</code>
Please note that Libpspio is still under active development and may randomly fail. Using it means that you are willing to contribute by testing it and reporting bugs.

Should you encounter any issue with Libpspio, please report it to its Launchpad bug tracker:
  * [[https://bugs.launchpad.net/libpspio]]

==== LibXC: reference library for exchange-correlation functionals ====

LibXC is a library providing a few hundreds of exchange-correlation functionals, including LDA, GGA, meta-GGAs, as well as correlations for hybrid ones. Its support is a must-have for any DFT code, since it will always provide more functionals and better tested ones than any scientific code would individually make available. It is already barely optional for Abinit and might become mandatory in the future, just as linear algebra.

You can download LibXC from the Octopus website:
  * [[http://www.tddft.org/programs/octopus/wiki/index.php/Libxc]]
LibXC is a C library, with Fortran interfaces. In order to make sure it will be usable by Abinit, please use the //--enable-fortran// option of configure, e.g.:
<code bash abinit-libxc-config.sh>./configure --prefix=/install/path --enable-fortran</code>
On some systems, you may encounter issues with shared libraries. Should this happen, just use the //--enable-static --disable-shared// options of configure in addition to the other ones.

Since exchange-correlation is a critical component of any DFT calculation, we highly recommend you to subscribe to the LibXC mailing list, in order to stay informed of any possible issue:
  * [[mailto:libxc-subscribe@tddft.org?subject=subscribe]] (direct email)
  * [[http://www.tddft.org/mailman/listinfo/Libxc]] (web interface)

==== LibYAML: YAML I/O support ====

[[wp>YAML|YAML (YAML ain't Markup Language)]] is a structured file format which has taken various concepts from various programming languages and text file formats to store data in a way that is both human-readable and machine-readable. Over the past few years, the use of YAML has gained a lot of momentum, in particular for scientific applications. The great interest of using YAML is that the produced data is typed and tree-structured (dictionaries, hastables), while the "markup" does not hinder the reading of the output.

Abinit is currently able to use the YAML part of the Flib library of BigDFT to produce YAML output. Please note that this feature is experimental and still requires some work. Using it means that you are ready to contribute and report bugs.

For more information, please consult the BigDFT website:
  * [[http://bigdft.org/Wiki/index.php?title=Fortran_library]]
  * [[http://www.bigdft.org/devel-doc/d9/d5f/group__FLIB__YAML.html]]

==== Wannier90: Maximally-Localized Wannier Functions (MLWFs) ====

Wannier90 is a Fortran package to compute and use Maximally-Localized Wannier Functions (MLWFs). It is mainly used in Abinit for transport calculations and to evaluate van der Waals interactions between atoms and molecules. It can be used either as a stand-alone executable or as a library.

The pristine version of Wannier90 can be downloaded from there:
  * [[http://www.wannier.org/]]
However, it cannot be used directly with Abinit, as it does not make available all the information needed by Abinit. This is why we provide a patched version on Launchpad:
  * [[https://launchpad.net/wannier90]]

The build of Wannier90 is relatively straightforward and only requires the location of linear algebra libraries. Following the instructions provided in the source package is generally sufficient and has proven seamless in most situations.

===== Alternatives =====

At present, the only alternative to correctly installing the external dependencies of Abinit are the [[https://launchpad.net/abinit-fallbacks|Abinit Fallbacks]]. They are developed as an independent project, although you will find a snapshot of their source code in every release of Abinit. Their main purpose is to be used by developers to test new versions of some of the external dependencies, as well as for busy users who wish to quickly test the minimum requirements they need for their calculations before properly installing them. Please note that **fallbacks should never be used for production calculations**. For more details, please consult our [[build:fallbacks|page about the Abinit Fallbacks]].