#

Installation notes for ABINIT v5.1

This file provides a description of the operations needed to install the ABINIT package, to generate the executable and to make the tests. It provides also the description of simple modifications of the package, for developers.

See a recent version of the new user's guide, for an introduction to the abinit package. See a recent version of the abinis help file for learning how to use the code. Both of them can be found in the Infos subdirectory.

Any comment or suggestion to improve the procedure will be welcome ! Simply contact the ABINIT group <
> .

##### Copyright (C) 1998-2009 ABINIT group (XG,DCA)
This file is distributed under the terms of the GNU General Public License, see ~abinit/COPYING or http://www.gnu.org/copyleft/gpl.txt .
For the initials of contributors, see ~abinit/doc/developers/contributors .

Goto : ABINIT home Page | Suggested acknowledgments | List of input variables | Tutorial home page | Bibliography

Help files : New user's guide | Abinis (main) | Abinis (respfn) | Mrgddb | Anaddb | AIM (Bader) | Cut3D | Optic | Mrgscr

## Summary :

- 1. How to get a version of ABINIT ?
- 2. How to make the executable and install them properly ?
- 3. How to make the internal tests ?
- 4. How to make the other tests ?
- 5. Things that are NOT in the installation files.
- 6. For developers : how to modify ABINIT ?

## 1. How to get a version of ABINIT ?

We will distinguish four cases :

1. you have a F90 compiler under UNIX/Linux (or MacOS X) and you want simply to compile the source files, and, from time to time, add a new file (this is the case of most users, system managers, and also many developers)
2. you run one of the UNIX/Linux (or MacOS X) platforms on which ABINIT is installed before each release, and you do not want to compile the source files, but to run the binaries (this is the case of some users).
3. you want to run ABINIT under DOS/Windows (this is the case of some other users).
4. you have a F90 compiler under UNIX/Linux (or MacOS X), as well as (free) softwares like bazaar, automake, autoconf, libtool, perl, python, and you want to have a full handle on the package (compilation, modification of files, writing of scripts ... this is the preferred case for developers).

Let us consider first the cases 1 to 3. You will have to download a package available on the web site. A different package is available for each case. In what follows, x.x.x represents the ABINIT version.

Case 1 (under UNIX/Linux or MacOS X, and you want to compile) :

> download the file abinit-x.x.x.tar.gz

> or

> download the five files abinitX-x.x.x.tar.gz where X is A, B, C, D or E

> The abinit-x.x.x.tar.gz gzipped tar file contains all the needed files, including :
> - the sources of the ABINIT code (also, the files needed for generating the FFTs, Numeric, Blas and Lapack libraries), in the directories "src" and "lib";
> - the documentation, in the directory "doc" ;
> - the complete set of tests, and the pseudopotentials needed for the tests, in the directory "tests" ;
> - all the scripts and information needed to produce makefiles, in other directories, especially "config".
> It does NOT contain the object files and the binary executable files.
> You might as well download separately five different tar.gz files named abinitA-x.x.x.tar.gz, abinitB-x.x.x.tar.gz abinitC-x.x.x.tar.gz, abinitD-x.x.x.tar.gz, and abinitE-x.x.x.tar.gz . This opportunity is provided in case you have a slow connection to the ABINIT Web site, and think your ftp connection might be not stable enough to download the entire abinit-x.x.x.tar.gz file : the five different files are each about one fifth of the single file, and altogether they contain also the full ABINIT package.

Case 2 (under UNIX/Linux or Mac OS X, and you do not want to compile) :

> download platform_seq-x.x.x.tar.gz, for the sequential version only,

> or

> download platform-x.x.x.tar.gz, for sequential and parallel versions (if both exist for the platform).

> Such gzipped tar files contains the binary executable files (sequential, or parallel, or both), the complete doc directory, and the different files needed to execute either the 5 internal tests (sequential version), or tests from the tests/paral directory (parallel version), or both. In what follows, we will focus on the sequential executable (called abinis). One should begin to use the parallel executable (called abinip) only when sufficient experience has been gained with abinis.
> The gzipped tar file does NOT contain the source files, neither the tests/fast, tests/v1, tests/v2, tests/v3, tests/v4, and other tests/* subdirectories (see section 4). The possible platforms are :
> - pclinux_pgi (PC under Linux, using the Portland Group Inc. compiler),
> - pclinux_ifc (PC under Linux, using the Intel compiler - a bit faster),
> - pclinux_pathscale (PC under Linux, using the pathscale compiler),
> - pclinux_g95 (PC under Linux, using the g95 compiler),
> - itanium2_ifc (PC-Itanium2 under Linux, using the Intel compiler),
> - ibm_pw5 (IBM with Power 5 processors),
> - ibm_44p (IBM model 44P with Power III+ processors),
> - compaq_ev56 (DEC/Compaq machines with EV56 alpha processors),
> - compaq_ev67 (DEC/Compaq machines with EV67 alpha processors),
> - hp_pa7200 (HP PA RISC processors, model 7200),
> - hp_pa8000 (HP PA RISC processors, model 8000),
> - hp_pa8500 (HP PA RISC processors, model 8500),
> - sgi_r12000,
> - sgi_r14000,
> - sun_ultrasparc,
> - fujitsu_vpp,
> - nec
> - macosx
> For the Intel/Linux machines, the binaries should contain all the library routines statically linked. They should be very portable (and they have been ported to more than 5 different machines in different countries, or of different constructors). However, they might have been compiled by a compiler that generates code that needs an IP number to work. So, some will not run if your machine has not been IP'ed. For the other platforms, the executable might not contain all the library routines (this depends whether they have been linked dynamically or not), so they might not be as portable.

Case 3 (you want to run ABINIT under DOS/Windows) :

> download intel_DOSWin_seq-x.x.x.exe, for the sequential version.

> This is a self-extracting zip file that has the same content as in Case 2 (likely not available before ABINITv5.2 or even ABINITv5.3).
> Note : in order to compile ABINIT under DOS/Windows, you need the PGI workstation environment. The procedure to be followed differs from what will be explained below, and will not be described. Contact the ABINIT group if needed.

In these three cases, execute the following actions :

> 1) Transfer the above-mentioned file(s) to your machine, in a directory suitable for the installation of the present version of ABINIT, and subsequent ones. You should have about 120 MB of disk space to install the code, maybe more, depending on the version, and the number of tests that you will do.

> 2a) Under UNIX/Linux, gunzip (on some machine you need gzip -d) and untar the file 'abinit-x.x.x.tar.gz' or 'platform-x.x.x.tar.gz' (or the sequential or parallel reduction of the later files) :

> > gunzip abinit-x.x.x.tar.gz | tar -xvf -

> > or

> > gunzip platform-x.x.x.tar.gz | tar -xvf -

> 2b) Under Windows, double-click the icon of the file intel_DOSWin_seq-x.x.x.exe to retrieve the files and directories. You can also run it as a command in a DOS window or use your favorite unzipping utility.

If correctly done, a main directory, denoted ~abinit in the present document (usually, its real name will be abinit-x.x.x, but it can bear another name if it comes from a platform-dependent tar file), and a whole set of subdirectories should have been created. One of them is called 'doc'. It contains many important informations. Many of the files it contains are .html files, that are placed on the Web site. However, many other files are not available in .html format, and are NOT placed on the Web site. In the future, keep in mind that the information that you are looking for but cannot find on the Web site might be in this directory, esp. doc/theory, doc/users, doc/psp_infos .

Case 4 (you have bazaar, perl, python, automake, autoconf and libtool installed on your machine) :

(Note : if you do not have these tools, and would like to have them, please consult your local computer guru, and the following pages ABINIT 5 in 10 steps, GNU software for ABINIT, GNU Arch Summary. If you want to develop, please have a bazaar branch created for you by contacting Yann Pouillon, as described in these pages.)

The first time you want to use bazaar (supposing you have installed it), you need three steps :

Define your id on you computer :

    baz my-id "your_name_your_email" (e.g. "John Dupont <dupont@domain.ext>")

Register the location of the ABINIT archive :

    baz register-archive sftp://antarion.pcpm.ucl.ac.be/store/archives/abinit-forge-v5

Define the current ABINIT bazaar archive as your default archive :

    baz my-default-archive "gonze@pcpm.ucl.ac.be--abinit-forge-v5"

Now, you are ready to download a working version of abinit, and can go to the following steps, that you will have to do everytime you restart the development of a new version of ABINIT.

Download the version of ABINIT on top of which you have to make your development :

    baz get name_of_your_development_branch

As an example, for the development of version 5.2, the name of your development branch should be abinit-devel--your_name--5.2 .
On your branch, you will have the permission not only to download, but also to commit your modifications. You might alternatively download other branches of the archives, but you will not be able to commit in these branches. So, do not start to modify these, you will not be able to include them afterwards in the archive.

Still another possibility, as concern your branch, would be to create a local archive for your daily work, this archive being linked to the main ABINIT archive. This very efficient technique is recommended, as it makes you more independent for the management of your work (you will be able to create new branches), but it is also a bit more elaborate. One big advantage of this technique is that people working with a laptop can develop and commit safely without a network connection. Please, consult the pages GNU Arch Summary, as well as the Web references mentioned in these pages.

## 2. How to make the executables ?

If you were in cases 2 or 3, then you already have the binary executables abinis, newsp, mrgddb, anaddb, ... so that you might skip the present section and go to the internal testing section. These executables are presently stored in the ~abinit/opt subdirectory. This might change in the future.

We now suppose that you have a F90 compiler and you want to compile the source files (case 1 and 4).

In most cases, you will have to provide to the 'make' utility some information: the location of the F90 compiler (and sometimes even the C compiler) on your machine, the adequate compiler options, and, if you want to produce the parallel binaries, the location of the MPI library on your machine.
Although the presently implemented building tools should be powerful enough to succeed to make the binaries without you giving such information, it has been seen that on a significant number of platforms, it was better still to give them.

This information should be stored in a file named hostname.ac , where "hostname" is the result of executing the command "hostname" on your machine, e.g. sleepy.pcpm.ucl.ac.be or dirac ...
There is a template for such a file, located in ~abinit/doc/config . Its name is template.ac . Examples of such files, that have been used for testing the package, can be found in ~abinit/doc/config/build-examples . By the way, the known problems observed for these different tests are mentioned in the ~abinit/KNOWN_PROBLEMS file, and the hostname.ac files are correspondingly indicated.

These files can be compared to the previously used 'makefile_macros' files (in ABINITv4 and prior). In general, you will notice that much less information is required. The new build system is much more clever than the previous one. The examples given in the ~abinit/doc/config/build-examples contain at most five definitions : F90 and C locations, F90 and C options, MPI library location (or the indication that MPI is not enabled). On the other hand, there are many other possible control flags, needed for advanced use. The activation of additional libraries (NETCDF, NQXC, XMLF90) should cause less problems than in the previous build system.

Your hostname.ac file can be placed in your home directory (this is new compared to the previous build system), in a new directory that you will name ~/.abinit/build

At that location, everytime you install a new version of ABINIT, the needed information will be found by ABINIT, so you do not have to care anymore about this file after the first installation.
On the other hand, if you need to play with several computers, you can place the hostname.ac file directoy in the ~abinit directory, where such a hostname.ac file will be also seen by the build system (and preferred over the one located in ~/.abinit/build ).
Finally, note that the first generation of a hostname.ac file can be done quite straighforwardly if you can rely on the 'makefile_macros' file that was used previously for your machines (in ABINITv4 or prior). As a first try, simply copy the values for the Fortran 90 compiler, perhaps the options for the libraries, and (eventually) the MPI location. As an example, for the machine sleepy.pcpm.ucl.ac.be, the three following information were given in the makefile_macros file :

- FC=/usr/pgi-4.0-2/linux86/bin/pgf90 -Bstatic
- FFLAGS_LIBS = -O2
- MPI_A=-L/usr/local/mpi-pgi4/lib -lmpichf90 -lpmpich -lmpich -lpmpich

from which the (reformatted) definitions can be set-up, in the hostname.ac file :

- FC="/usr/pgi-4.0-2/linux86/bin/pgf90"
- with_fortran_optflags="-O2 -Bstatic"
- with_mpi_prefix="/usr/local/mpi-pgi4"

All other information from the makefile_macros file are not needed anymore. Compare the file (from version 4.6.5)
~abinit/Machine_dept_files/Intel_P6/makefile_macros.PGI4.0.2static_sleepy
with the file (from version 5.0.1)
~abinit/config/build-examples/i686-linux-gnu-gnu-pgi4.0_sleepy.ac

When the hostname.ac file is ready, you have to issue, in the ~abinit directory :

Case 1 (you got the package from the Web site)

- ./configure (or first create a tmp directory, then cd tmp, then ./configure)
- ./make (or ./make multi for using several processors on a SMP machine)
- (optionally) ./make install

Case 4 (you got the package from the ABINIT archive)

- ./config/scripts/makemake
- ./configure (or first create a tmp directory, then cd tmp, then ../configure)
- make (or make multi for using several processors on a SMP machine)
- (optionally) make install

Among other things, the 'makemake' step produces the information needed for the autotools (autoconf and automake), including the list of executables, dependencies, files to be compiled ... It might take one minute or less. The 'configure' step produces the set of Makefile files (among other things), taking into account information about your machine and the hostname.ac file. It is also one minute long, or less. The 'make' step compiles everything, according to the Makefile files produced in the prior step. The time to make everything is highly dependent on the compiler and platform. On a 2.8 GHz bi-proc machine (using make multi), the whole compilation is about 4 minutes. On some other platforms, with only one processor, it might be more than one hour.

The executables will be located in the subdirectory ~abinit/src/main, if you have chosen to issue ./configure in the ~abinit directory. If you have issued ./configure in another directory, it will be placed accordingly.

The 'make' command can also be used in many different ways, by mentioning one or more targets. A (partial) list of targets for users can be obtained by typing

    make help

Additional targets, for developers, can be obtained by typing

    make help_dev

It is possible to compile only one of the executable, just after the configure step by typing
make name_of_the_binary (where name_of_the_binary can be abinis, abinip, abinitgw, newsp ...)
These are only a tiny fraction of the things that you can realize thanks to 'make'. Moreover, there are also 'Makefile' files in most of the subdirectories of ABINIT, with often their own (partial) list of targets for users (and also sometimes for developers). To obtain these lists, go to the directory, and type

    make help

or

    make help_dev

## 3. How to make the internal tests ? (sequential version only)

The abinis code has five small internal tests, that can be issued automatically, and that check themselves whether the results that have been obtained are right or wrong. At most 3 MB of memory and 1 MB of disk space are required on your machine for these tests to work. These tests are available in all cases (whether you have got the package from the Web or from the ABINIT archive).

You can begin with the test number 1. Simply issue the command :

> make test1

It will run during a few seconds. It should print

    Running built-in test 1

     Status file, reporting on test             1

     OK for total energy
     OK for nuclei positions
     OK for forces
     OK for stresses

This means that the internal test 1 ran successfully. If you do not get this message, then the executables were not properly generated, or there is a problem with the make and scripts that drive the internal test. In this case, after having tried to solve the problem by yourself, you should contact somebody in the ABINIT group.

Supposing test1 was OK, then you might issue the command

> make tests_in

The test 1 will be done once more, followed by the 4 other internal tests. Again, we hope that you will get the positive diagnostics for the other tests.

For further information on these internal tests, see the file ~abinit/tests/built-in/README .

You might now read the new user's guide, in order to learn how to use the code. This is useful if you consider that the installation has been successful, or if you want to continue the tests.

## 4. How to make the other tests ?

(Case 1 and 4 only, since in cases 2 and 3, only the minimal testing tools have been included in the corresponding package.

Although it is possible to make the other tests without knowing really how to use the code (since all steps involved - the run and subsequent analysis - are done automatically), it is the right time to read the new user's guide, and then to follow the four basic tutorials, see the entry page for the tutorials.

Let us pursue with the testing procedure. Go to the ~abinit/tests directory, and issue :

> make help

A whole list of possible sets of tests is given. A reasonable set of tests (fast, v1, v2, v3 and v4), produced with a summary, can be run automatically by

> make tests_dev

This is the recommended procedure for developers. In order to execute these tests, you will need a larger disk space than for the simple installation of the code (the total additional disk space required is on the order of 120 MB).

Let us now examine the different subdirectories.

~ABINIT/tests/fast is the simplest, and its content will be described in some detail below. For tests of the parallel version (abinip) see the directory test/paral, as well as the ~abinit/doc/paral_use text file. For tests of the response function features of abinis, and for tests of mrgddb and anaddb, see the subdirectories test/v2. The other directories test/v3 and test/v4 presents further tests of recently implemented features of ABINIT.

1) test/fast (for the sequential version only)

This subdirectory contains a basic set of tests of the code, aimed at testing whether the code is coherent in time (successive versions), and exercising several parts of the code. However, they do not examine its accuracy on physical problems, mainly because the number of plane waves used is too small, and some tests are not run to self-consistent convergence. 32 MB of memory should be enough for these tests.
Read the ~abinit/test/fast/README file carefully (at least the beginning).
To run the tests, simply issue, in the ~abinit/tests directory :

> make tests_fast

A more detailed way to control the set of tests is obtained by typing :

> make help_dev

'make tests_fast' will create a directory whose name will be build from the machine name and today's date. All the results will be in that directory. The output files will be automatically compared, thanks to a 'diff' command, to a set of reference files (the corresponding difference files are prefixed by 'diff.').

In addition to 'diff', another comparing tool called 'fldiff' -for 'floating diff'- is also used. It treats in a more clever way the comparison of floating numbers between the output files and the reference files. As used presently, for each run, one single file, called 'fldiff.report', will be produced. If for one test case, the two files differ by the number of lines, the 'fldiff.report' file will report that it cannot compare the two files. Usually this problem will be seen at the level of 'command signs' appearing sometimes in the first column of the output files, so a typical error message (announcing something went wrong) will be:

> Case_1
> 22
> The diff analysis cannot be pursued : the command sign differ.

By contrast, it will identify the floating numbers and ignore their differences if they are within some prescribed tolerance, or if the difference is not relevant. For example, it is able to ignore the differences in timings. If everything goes fine for a test, fldiff should identify only the differences in :

- the dates of execution (eventually) ;
- the version numbers (eventually) ;
- the platform description (eventually) ;
- the overall execution time (this is ALWAYS printed, even without differences).

So, a successful execution of one test case may be announced as follows in the fldiff.report file :

> Case_1
> 2
> < Version 4.3.2 of ABINIT
> > Version 4.3.0 of ABINIT
> 5
> < Starting date : Fri 27 Jan 2004.
> > Starting date : Sat 31 Jan 2004.
> 202
> < +Overall time at end (sec) : cpu= 7.1 wall= 8.0
> > +Overall time at end (sec) : cpu= 7.3 wall= 8.0

The fldiff.report file will have one such section for each test_case that was run. It begins with the number of the test case, then includes a few blocks of three lines: the number of the line where something is happening, followed by the content of the two lines.

If differences (besides those described above) are found, then there is a problem, or the double precision tolerance needs to be adjusted (as time goes, this should become better). More information on the fldiff script can be found in the ~abinit/tests/Scripts/fldiff.pl file.

Usually, these tests are run with the sequential version of the code only. It is possible to make them using the parallel version of the code, type

> make help_dev

in the ~abinit/tests directory for some information about this.

2) test/v1

This directory contains tests built in the same spirit as those in the test/fast directory, but that exercise other basic features, like the treatment of metals, the GGA, the new pseudopotentials, the multi-dataset mode, the cell parameters optimization, and the spatial symmetry groups database.
These were developed during the development time of the version 1 of ABINIT.
Of course, the automatic difference procedure only compares to recent runs of the ABINIT code. As for the 'fast' test cases, the fldiff.report file is also available. 64 MB of memory should be enough for these tests.

3) test/v2

This directory contains tests built in the same spirit as those in the test/fast directory, but that exercise features not present in the Plane_Wave code, nor in version 1 of the ABINIT package, mainly the response function features, and the use of the mrgddb and anaddb codes. Again, the automatic difference procedure only compares to recent runs of the ABINIT code. As for the 'fast' test cases, the fldiff.report file is also available. 64 MB of memory should be enough for these tests.

4) test/v3 and test/v4

These directories contain tests built in the same spirit as those in the test/fast directory, but that exercise features not present in the Plane_Wave code, nor in version 1 or 2 of the ABINIT package, noticeably the use of the GW code, the utilities Cut3d, AIM, .., the PAW ... . Again, the automatic difference procedure only compares to recent runs of the ABINIT code. As for the 'fast' test cases, the fldiff.report file is also available. 64 MB of memory should be enough for these tests.

5) test/cpu (for the sequential version only)

This subdirectory contains the scripts, and input files needed for testing the cpu time, either on progressively finer real space grids, or on progressively bigger unit cells. Please read the README file of this directory. Also for this suite of tests is activated with

> make tests_cpu

Unlike in the previous case, many directories will be created (more than 10 in the present version). Their name begins with the test name (A1, A2, A3, A4, B1, B2, B3, B4, C3, D3), and is followed by the machine name and the date. Inside these directories, many runs are done.
There is a 'report' file that summarizes the timing of the different runs, and there is a 'diff' file, that compares these timings with the reference (output files from a PII at 450 MHz, usually). The structure of these tests is more complex than that of the test/fast and test/v1 directories. The tools used are the 'serie' scripts (serieA,serieB, serieC and serieD) as well as the 'getrep' script. For an explanation, contact the ABINIT group. For the largest tests (B and D series), up to 200 MB of central memory are required.

6) test/paral (needs both abinis and abinip)

This directory contains tests built in the same spirit as those in the test/fast directory, but that exercise the parallel version of the ABINIT code.
The script in that directory (not in the main directory) considers one of the different input files, and for this file, it will perform first a sequential run (using abinis), then use the parallel code (abinip) with one processing node, then perform different parallel runs with an increasing number of processing nodes. As for the other series of test, the diff and the fldiff utilities are used automatically.

## 5. Things that are NOT in the installation packages.

- Pseudopotentials :
  The installation files contain a few pseudopotentials, for testing purposes, see ~abinit/tests/Psps_for_tests. But many other pseudopotential have been generated. There exist presently two complete sets of ready-to-use LDA pseudopotentials, for the whole periodic table : those generated by Doug Allan and Alex Khein for the plane_wave code, and those published by Hartwigsen, Goedecker and Hutter (Phys. Rev. B 58, 3641 (1998)). Also, the Fritz-Haber-Institute code, that is freely available at http://www.FHI-Berlin.MPG.DE/th/fhi98md/fhi98PP, can be used to generate LDA as well as GGA pseudopotentials, that can be read by the code after minor modifications, see the Web site.

- The Web site http://www.abinit.org contains many other things ...
  The benchmarks results, the mailing lists, ...

## 6. For developers : how to modify the code ?

You must be in case 1 or 4 (you have a compiler, and Makefile files).

If you want simply to modify the content of an existing file (e.g. one of the Fortran files, located in one of the src/* directories), and recompile the code, the procedure is quite simple : modify that file, and reissue

> make

in ~abinit.

If you want to add a new file, there is a difference between case 1 (you do not have the autotools) and case 4 (you have the autotools).

In both cases, you must add the file name in the abinit.src file of the corresponding directory. As an example, suppose that you want to add a new routine named blork.F90 in the directory ~abinit/src/03nonlocal . Then, you must also declare it in the file ~abinit/src/03nonlocal/abinit.src

In the case 4, you have now to reissue makemake, configure and make (see the section 2).

In the case 1, you do not have the autotools, so that you must also modify by hand the Makefile.in of the directory where the new file has been added (e.g. ~abinit/src/03nonlocal/Makefile.in), then issue configure and make in the top directory.

Finally, if you want to produce the source package abinit-x.x.x.tar.gz , type

> make dist

in ~abinit . Do not forget to change its name (e.g. add your name after x.x.x, to identify that this is a modified version of ABINIT.

Goto : ABINIT home Page | Suggested acknowledgments | List of input variables | Tutorial home page | Bibliography

Help files : New user's guide | Abinis (main) | Abinis (respfn) | Mrgddb | Anaddb | AIM (Bader) | Cut3D | Optic | Mrgscr