#

Installation notes for ABINIT v5.2

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 ?

- 1.A. ... if you want a full handle (preferred case for developers - need some expertise)
- 1.B. ... if you want to get the sources and compile them (this is the case of most users, and might also be sufficient for basic developments)
- 1.C. ... if you are happy with the executables, and you use a Unix/Linux/Mac OS X -based platform
- 1.D. ... if you are happy with the executables, and you use a Windows platform

- 2. How to make the executables ?
- 3. How to make the internal tests ?
- 4. How to make the speed tests ?
- 5. How to make the other tests ?
- 6. Things that are NOT in the installation files.
- 7. For developers : how to modify ABINIT ?

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

We will distinguish four cases :

- 1.A. 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). We will sometimes refer to this case as the "autotools working mode".
- 1.B. 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, modify and/or add a new file (this is the case of most users, system managers, and also many developers). We will sometimes refer to this case as being "without autotools".
- 1.C. 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).
- 1.D. You want to run ABINIT under Windows (this is the case of some other users).

You should read only the appropriate section (you can safely ignore the others ...).

### 1.A. To get a full handle of ABINIT

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... We will sometimes refer to this case as the "autotools development mode". 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 or Jean-Michel Beuken, as described in these pages.

It is strongly advised to subscribe to the ABINIT developer's mailing list AND the ABINIT GNU Arch mailing list, if you want to be able to get the latest information concerning the autotools development mode.

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.3, the name of your development branch should be abinit-devel--your_name--5.3 .
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.

Now, issue

> ./config/scripts/makemake

or the shorter

> */*/makemake

This command initializes a whole set of files and scripts, needed for the autotools, as well as for the global work on ABINIT sources. This initialization might take between one and two minutes.

After this initialisation, you can proceed to the generation of the executables, as described in section 2.

### 1.B. To get the sources and compile them

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, modify and/or add a new file. This is the case of most users, system managers, and also many developers. If you want to modify and/or add a new file, please consult the section 7. For developers : how to modify the code ? after reading the present section.

In what follows, x.x.x represents the ABINIT version.

Now :

> download, gunzip and untar the file abinit-x.x.x.tar.gz

> or

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

More detailed explanations ...

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.

So, execute the following actions :

> 0) Under Mac OS X, open a terminal session, so you can work as if it were a Unix platform.

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

> 2) gunzip (on some machine you need gzip -d) and untar the file 'abinit-x.x.x.tar.gz' :

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

If correctly done, a main directory, denoted ~abinit in the present document (usually, its real name will be abinit-x.x.x) 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 that you cannot find on the Web site) might be in this directory, esp. doc/theory, doc/users, doc/psp_infos .

You might now go to the section 2.

Do not forget : if you want to modify and/or add a new file, please consult the section 7. For developers : how to modify the code ? after reading the present section.

### 1.C. To get the executable binaries for a Unix/Linux platform

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

In what follows, x.x.x represents the ABINIT version. You should identify, from the ABINIT download page for the version that you want, whether the binaries are available for your specific platform. See the binaries summary table, in case you do not find it.

The platform name is identified by platform in what follows.

Now :

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

> or

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

More detailed explanations ...

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. 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),
- sgi_r14000,
- 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.

So, execute the following actions :

> 0) Under Mac OS X, open a terminal session, so you can work as if it were a Unix platform.

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

> 2) gunzip (on some machine you need gzip -d) and untar the file 'platform_seq-x.x.x.tar.gz' or 'platform_seqpar-x.x.x.tar.gz' :

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

> or

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

If correctly done, a main directory, denoted ~abinit in the present document (usually, its real name will be abinitbin-x.x.x), 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 that you cannot find on the Web site) might be in this directory, esp. doc/theory, doc/users, doc/psp_infos .

The binary executables abinis, newsp, mrgddb, anaddb, ... are presently stored in the ~abinit/opt subdirectory (this might change in the future.)

You might now go to the internal testing section.

### 1.D. To get the executable binaries for a Windows platform

You want to run ABINIT under Windows.

In what follows, x.x.x represents the ABINIT version.

You should identify, from the ABINIT download page for the version that you want, whether the Windows package has been prepared. See also the binaries summary table. Now,

> download intel_DOSWin_seq-x.x.x.exe

This is a self-extracting zip file. 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 window or use your favorite unzipping utility.

If correctly done, a main directory, denoted ~abinit in the present document, 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 that you cannot find on the Web site) might be in this directory, esp. doc/theory, doc/users, doc/psp_infos .

The binary executables abinis, newsp, mrgddb, anaddb, ... are presently stored in the ~abinit/opt subdirectory. This might change in the future. No parallel executable has yet been generated for Windows.

Note : in order to compile ABINIT under Windows, you need the PGI workstation environment. The procedure to be followed differs from what is explained for the Unix/Linux platforms, and will not be described here. Contact the ABINIT group if needed.

You might now go to the internal testing section.

## 2. How to make the executables ?

If you got the binary executable package, you should skip the present section and go to the internal testing section. These executables are presently stored in the ~abinit/opt subdirectory.

We now suppose that you have a F90 compiler and you want to compile the source files.

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.

Supposing that you are in the lucky case where the build system is able to find all the information, then the build of ABINITv5 is very simple. Issue :

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

Well, it might also be that only one additional information is needed, in which case something like

- configure FC=95
- make

might work. In both cases, let's explain a bit what is done, and the further possibilities.

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 takes 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

Finally,

    make install

will install abinit in the /opt/etsf directory (etsf is the abbreviation of European Theoretical Spectroscopy Facility). In the directory ~abinit/doc/config , you will find two important help files, in case you want to go further : build-howto.txt and using-configure.txt .

Let's come back to the case where the build system needs some more information. 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 ... , and taking the first word of the returned chain of character, e.g. sleepy or dirac ...
There is a template for such a file, located in ~abinit/doc/config . Its name is build-config.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 at the beginning of this file.

The hostname.ac file can be compared to the previously used 'makefile_macros' file (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 most examples given in the ~abinit/doc/config/build-examples contain about 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 might 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 directory 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 ) or in your build directory (like ~abinit/tmp). As mentioned above, you might even type at the terminal the definitions contained in the hostname.ac file.

Note the order of precedence for the location of the hostname.ac file (or command-line information), in case more than one possibility is used, (decreasing order of precedence) :

- Command line (overcome all other information)
- Your build directory (~abinit/tmp)
- The ABINIT top directory (~abinit)
- ~/.abinit/build
- /etc/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 new file
~abinit/doc/config/build-examples/i686-pgi4.0_sleepy.ac

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

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

## 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, and then to follow the four basic tutorials, see the entry page for the tutorials. This is useful if you consider that the installation has been successful. Or you might continue to read the present Web page, and try to perform the speed tests, as well as the other tests.

## 4. How to make the speed tests ? (sequential version only)

When the internal tests run correctly, you might try to insure that your installation of ABINIT has produced an executable whose speed is "reasonable". For this purpose, you might issue, in the directory ~abinit/tests ,

> make tests_speed

Note that, in case you start from one of the binary packages, this might work only if the software perl is available on your computer and perl is aliased to a working perl binary. To check this, issue

    perl --version

You should get something like :

    This is perl, v5.8.5 built for x86_64-linux-thread-multi

    Copyright 1987-2004, Larry Wall

    Perl may be copied only under the terms of either the Artistic License or the
    GNU General Public License, which may be found in the Perl 5 source kit.

In case perl is not installed or available, ask your local computer guru.

On a PIV/XEON 2.4GHz , these tests need about 2 minutes. All the results are analyzed automatically, and summarized in the file ~abinit/tests/,summary_speed . You can examine these results, and compare them to those that you can find on the Benchmark pages of ABINIT. Try to find a platform similar to yours. The comparison of frequencies is important, although a simple rescaling should be enough to compare similar platforms with different frequencies. Supposing the comparison gives a 20% difference, your installation is likely fine. If you find much longer times than those advertised, it is likely that you have to improve your hostname.ac file, by finding better compiler flags (see section 2 ).

Supposing you have not yet done so, you might now read the new user's guide, in order to learn how to use the code, and then to follow the four basic tutorials, see the entry page for the tutorials. Alternatively, you might want to continue the tests.

## 5. How to make the other tests ?

(These tests cannot be done if you only got the binaries : 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 important 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 (those contained in the fast, v1, v2, v3, v4 and v5 directories), 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). A more detailed way to control the set of tests is described by typing :

> make help_dev

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, test/v4 and test/v5 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.
The description of the tests can be found at the end of the ~abinit/test/fast/README file .
To run only the tests in this directory, simply issue, in the ~abinit/tests directory :

> make tests_fast

'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 (in ~abinit/tests/fast/Refs). The corresponding difference files are prefixed by 'diff.'.

In addition to 'diff', there are two other levels of automatic analysis : one based on a comparing tool called 'fldiff', producing 'fldiff.report' files, and another where the output of 'fldiff' is further analyzed, and produce a brief report called 'report'. The latter step is only performed in case all the tests cases of one directory are performed (including the case where tests of different directories are performed, like with the "make tests_dev" instruction). The one-line summaries produced by fldiff (see later) are compared with a database (see ~abinit/tests/fast/Input/report.in). This procedure produces a file called "report", in which there is a one line assessment of the behaviour of each test : succeeded (everything is OK), passed (the test is OK for users in production), passed marginally (the test is within 1.5 of the usually accepted deviation, which is likely OK for most applications - still to be improved by the development team, though), failed (there is a problem, the deviation is usually not accepted). This is by far the most convenient tool to analyze the automatic tests of abinit. As of v5.2.3 , the vast majority of tests cases succeed or pass on all platforms that are used by the developer team in Louvain-la-neuve, except test_v2#15, test_v2#48 and tutorial#elphon_5 , where fluctuations from one machine to another are still to be solved. This problem is mentioned in the file ~abinit/KNOWN_PROBLEMS , see problem P52.1 . Additionally, there might be specific problems for some test case for some platforms, also mentioned in ~abinit/KNOWN_PROBLEMS. So, apart of the known problems, mentioned in this file, the "report" file should mention, for each test case, only "succeeded" or "passed".

The comparing tool 'fldiff' -for 'floating diff'- performs in a more detailed way the comparison of floating numbers between the output files and the reference files than in the case of a 'diff' command. As used presently, for each run inside one directory, one single file, called 'fldiff.report', will be produced, and gather the analysis for all tests in that directory.
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
> Summary Case_1 : no significant difference has been found

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. Finally, there is a one-line summary for each test case.

More information on the fldiff script can be found in the ~abinit/tests/Scripts/fldiff.pl file.

In case all the tests cases of one directory were performed, there is an additional analysis step, where the one-line summaries produced by fldiff are compared with a database (see ~abinit/tests/*/Input/report.in). This procedure produces a file called "report", in which there is a one line assessment of the behaviour of each test : succeeded (everything is OK), passed (the test is OK for users in production), failed (there is a problem).

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 and report files are 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 and report files are also available. 64 MB of memory should be enough for these tests.

4) test/v3, test/v4 and test/v5

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 and report files are 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 PIV at 2.8 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 ~abinit/tests/Scripts/drive-parallel-tests.sh 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, and fldiff.report and report files are produced automatically.

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

- Many pseudopotentials are not in the installation package:
  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, ...

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

(Of course, you cannot modify the code if you only downloaded a binary package).

### 7.1. To modify a file (arguments unchanged).

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), without changing its list of arguments, and recompile the code, the procedure is quite simple : modify that file, and reissue

> ./make

in ~abinit.

### 7.2. To modify a file (arguments changed).

If you want to modify the content of an existing Fortran file as well as the list of arguments, and recompile the code, the procedure is to modify that file, and then issue, in the ~abinit directory :

> */abilint . .

> ./make

Do not forget the two dots in the abilint command.

### 7.3. To add a Fortran file.

If you want to add a new Fortran file, there is a difference whether you work with or without 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
Note that the choice of directory is important. You should choose to put your new routine in a directory that has a prefix number (e.g. 02 for 02nlstrain) higher than all the directories that contain routines you will use (except if the called routines are in the same directory), and smaller than all the directories that call your routine (except for routines that are in the same directory as yours).

If you work with the autotools, you have now to reissue

> */*/makemake

> ./configure

> ./make

(see the section 2).

If you work without the autotools, you must also modify by hand (i.e. find the places where the Fortran files are listed, and complete the list) the Makefile.in of the directory where the new file has been added (e.g. ~abinit/src/03nonlocal/Makefile.in), then issue

> */abilint . .

> ./make

in ~abinit.

### 7.4. To generate the source package.

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

### 7.5. To generate a binary package.

If you want to produce a binary package abinitbin-x.x.x.tar.gz , type

> ./make seq

or

> ./make seqpar

in ~abinit . Do not forget to change its name (e.g. first, add your name after x.x.x, to identify that this is a modified version of ABINIT, and second, change the generic "abinitbin" to the nickname of the platform, like pclinux_pathscale, to give pclinux_pathscale_seq-x.x.x.tar.gz).

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