Installation notes for ABINIT v2.0


This file provides a description of the operations needed to install the ABINIT package, to generate the executable and to make the tests.

See a recent version of the file 'new_user_guide', for an introduction to the abinit package. See a recent version of the file 'abinis_help' 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.

Created 981109
Last updated XG 990707

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


Summary :


How to get a version of ABINIT ?

We will distinguish two cases :

  1. you have a F90 compiler and you want to compile the source files.
  2. you run one of the platforms on which ABINIT is installed before each release, and you do not want to compile the source files.

In both cases, all the installation files are available on the web site (preferred means of distribution).

You might also get them by direct access to a machine in Louvain-la-Neuve, supposing you have received a corresponding UserID. In case 1), you should have an access to hilbert.pcpm.ucl.ac.be (or equivalently, bohr.pcpm.ucl.ac.be, since the disks are NFS-shared). In case 2), you must access the corresponding platform in Louvain-la-Neuve (however, the installation files for the Linux/Intel and CRAY_T3E platforms are located on hilbert.pcpm.ucl.ac.be).

From now on, we suppose that you have either access to the web site, or to the machine and the proper official directory.

You must get the following files (x.x.x is the version):

Case 1 (you want to compile) : src_tests_x.x.x.tar.gz

This gzipped tar file contains all the sources of the ABINIT code (including the files needed for generating the FFTs, NumRecip and Lapack libraries), the complete Infos directory, the complete set of Tests, all the scripts and makefiles, the pseudopotentials needed for tests.
It does NOT contain the object files and the binary executable files.

Case 2 (you do not want to compile) :

platform_x.x.x.tar.gz, for sequential and parallel versions (if both exist for the platform), or

platform_seq_x.x.x.tar.gz, for the sequential version only, or

platform_par_x.x.x.tar.gz, for the parallel version only (if it exists for the platform).

This gzipped tar file contains the binary executable files, the complete Infos directory, and the different files needed to execute either the 5 internal tests (sequential version), or tests from the Test_par directory (parallel version), see below. In what follows, we will focus on the sequential version (called abinis). One should begin to use the parallel version (called abinip) only when sufficient experience has been gained with abinis.
The gzipped tar file does NOT contain the source files, nor the Test_fast, Test_v1, Test_v2 and Test_cpu directories, and the corresponding pseudopotentials. The possible platforms are : intel_linux, ibm_pw2, dec_osf, hp_pa7200, hp_pa8000, sgi_r10000, cray_t3e and fujitsu_vpp . For the Intel/Linux machines, the binaries 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 construction ). However, they have been compiled by a compiler that generates code that needs an IP number to work. So, they will not run if your machine has not been IP'ed. For the other platforms, the executable does not contain all the library routines (they are linked dynamically), so they might not be as portable. The portability of the executable has been checked only for IBM PW2 and SGI Origin 2000 platforms.

So, execute the following actions :

1) Transfer the above-mentioned file(s) to your machine, in a directory referred to here as ~local_ABINITvx.x.x . You should have about 50 MB of disk space to install the code, maybe more, depending on the version.

2) Gunzip (on some machine you need gzip -d) and untar the file 'src_tests_x.x.x.tar.gz' or 'platform_x.x.x.tar.gz' (or the sequential or parallel reduction of the latter file) :

gunzip src_tests_x.x.x.tar.gz | tar -xvf -

or

gunzip platform_x.x.x.tar.gz | tar -xvf -

If correctly done, a whole set of subdirectories should have been created. One of them is called 'Infos'. It contains many important informations. In particular, you will find the description of the different subdirectories in the ~local_ABINITvx.x.x/Infos/dirs_and_files file. This file also describes the content of the Infos directory, that is, all the information files.

*** It is strongly adviced to the installer to read (and print) NOW the ~local_ABINITvx.x.x/Infos/dirs_and_files file. ***


How to make the executables ?

If you were in case 2, then you already have the binary executables abinis, newsp merge and ifc, so that you might skip the present section and go to the internal testing. However, just for fun, you can issue the make command, in the ~local_ABINITvx.x.x directory :

make

This will print the list of available keywords for the make utility.

We now suppose that you have a F90 compiler and you want to compile the source files (case 1). You must provide to the 'make' utility some information: the location of F90 and C compilers on your machine, the cpp utility, the blas library ... For this, you must create in the ~local_ABINITvx.x.x directory a file (or a symbolic link) named 'makefile_macros', that you will have to design starting from already existing example files. Examples of such files are contained in the subdirectories of the ~local_ABINITvx.x.x/Machine_dept_files directory. Actually, if one of the existing 'makefile_macros' file is suitable for you, you will have simply to issue an instruction like the following :

ln -s Machine_dept_files/DEC/makefile_macros.newton makefile_macros

(here, a symbolic link is created, so that 'makefile_macros' refers to Machine_dept_files/DEC/makefile_macros.newton , a file suitable for the DEC machine named 'newton' at the PCPM). In order to generate a new 'makefile_macros' file, a help file called 'help.makefile_macros' can be found in the ~local_ABINITvx.x.x/Infos directory. You can ask some help to the ABINIT group. When you have succeeded to create one such file, please send it to us, so that it can be maintained in the next versions of the code.

When the 'makefile_macros' file is ready, you will have to issue the 'make' command, followed by some keyword.

To get the sequential version of all the executables, you must type :

make allseq

or

make allseq >& log.file

(allseq is an abbreviation for all sequential executables; log.file can be any filename, and is useful when the messages from make are too long)

Issuing this 'make allseq' command will trigger a whole set of actions (not easy to follow, as you will see).
The make utility will use the file 'Makefile', that calls a script called 'makemake', to produce another makefile, called 'tmp_makefile', that calls different 'makemake' scripts in different subdirectories, that create themselves 'tmp_makefile' files, that compile the fortran source (and eventually one C file), create libraries and link the different objects.
Moreover, usually, this works without problem !

Let's us suppose that you do not issue the powerful 'make allseq' command, but that you want to create one-by-one the libraries and executables.

Then, for the sequential version, you must create :

Alternatively, the three libraries can be created at once by issuing 'make libs'.

Then, you can issue 'make abinis' to make the sequential version of abinit, and 'make newsp' to make newsp, the wavefunction translator. The latter is needed for different tests of abinis (see below). You can also issue 'make merge' to make the code that merge the derivative databases, and 'make ifc' to make the code that analyze interatomic force constant.

In order to get a transferable executable on Intel/Linux machines, it might be needed to generate a static BLAS library. For this purpose, issue 'make blas'. Be consistent with this choice, at the level of the 'makefile_macros' file. This possibility is also used for the Fujitsu machines.

Informations needed to generate the parallel version of ABINIT can be found in the ~local_ABINITvx.x.x/Infos/paral_use file.

Suppose that something is going wrong in one of the above-mentioned steps, then, you can issue one of the 'clean_xxx' keywords (those mentioned by typing 'make') to clean the directory where something wrong happened.

With a bit of luck, you will succeed to generate the executables. You are ready to perform the tests.


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

The abinis code has five 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 is required, and 1 MB of disk space.

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

make test1

It will run during a dozen of seconds. It will first print 

cd Test_in; rm -f *1*o* *1*S ; ../abinis < test1.files > test1.log 2>&1 &
Test_in/test_end Test_in/test1 ; cat Test_in/test1_STATUS

then, you will eventually (if you are on a slow machine) see different instances of the status file, like the following :

Status file, with repetition rate 20 , status number 101 

Level abinit : call gstate
Level gstate : call brdmin
Level brdmin : call scfcv_ini
Level scfcv : call vtorho
istep = 2
Level vtorho : compute rhog

then, the important information is as follows :

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.

Note : the script detects the end of the run by using the 'ps' command following by a 'grep' command. This can lead to strange effects if a file whose name contain 'abinis' is currently visualized, or if another job is running under a name that contains 'abinis'.
So, close your files before running the tests, and also check that there are no running jobs whose name contains 'abinis'.

Supposing test1 was OK, then you have to issue the command 'make tests'.

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. Altogether, these tests are about 1 minute on a PPro 200 MHz machine where no other job is running.

For further information on these internal tests, see the file ~local_ABINITvx.x.x/Test_in/README .

You might now read the ~local_ABINITvx.x.x/Infos/new_user_guide file, 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.


How to make the other tests (case 1 only)?

(Case 1 only, since in case 2, only the minimal testing tools have been transferred)

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 ~local_ABINITvx.x.x/Infos/new_user_guide file.

After this reading, should look at the subdirectory Test_fast, and, later, Test_v1 and Test_cpu, where tests of the sequential version of ABINIT (abinis) can be done automatically. For tests of the parallel version (abinip) see the directory Test_paral, as well as the ~local_ABINITvx.x.x/Infos/paral_use file. For tests of the response function features of abinis, and for tests of merge and ifc, see the subdirectory Test_v2.

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 100 MB). After having checked the results of the tests, the user can easily retain the output files in a compressed form, and get rid off the wavefunction files by issuing

make decrease_size_tests

in the ~local_ABINITvx.x.x directory. Separate commands are available for each of the Test directories.

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 many 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 (with no other application running, however).
Read the ~local_ABINITvx.x.x/Test_fast/README file carefully (at least the beginning), then read the beginning of the scripts 'Run'.
To run the tests, simply issue :

(Run machine_name) >& log

where machine_name will usually be the name of your machine (any other character string is fine, however).

The script 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, either from the plane_wave code (the corresponding difference files are prefixed by 'diff.'), or from a recent run of the ABINIT code (the corresponding difference files are prefixed by 'difnew.').

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 in the 'Run' script, for each run, only 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 (fldiff should become an expert system in this respect : for example, in the present version, it is already able to ignore most differences in timings). If everything goes fine for a test, fldiff should identify only the differences in :

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

Case_1
2
< Version 1.9.x of ABINIT
> Version 1.8.2 of ABINIT
5
< Starting date : Mon 1 Feb 1999.
> Starting date : Thu 28 Jan 1999.
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 ~local_ABINITvx.x.x/Utilities/fldiff file. If needed, you can send by e-mail the fldiff.report to the ABINIT group for help understanding it and fixing possible bugs.  

Note that the Run script assumes that the tcsh shell can be found in /bin . If this is not the case, its first line must be changed. The use of tcsh is preferred over csh because the latter is not stable on some machines.

2) Test_v1  (for the sequential version only)

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, 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 (with no other application running, however).

Note that the Run script assumes that the tcsh shell can be found in /bin . If this is not the case, its first line must be changed.

3) Test_v2  (for the sequential version only)

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 merge and ifc 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 (with no other application running, however).

Note that the Run script assumes that the tcsh shell can be found in /bin . If this is not the case, its first line must be changed.

4) 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, you have simply to issue

(Run machine_name) >& log

Unlike in the previous case, many directories will be created (8 in the present version). Their name begins with the test name (A1, Am2, A3, B1, Bm2, B3, 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 PPro at 200 MHz). 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.

Note that the different Run* scripts assumes that the tcsh shell can be found in /bin . If this is not the case, their first line must be changed.

5) 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 'Run' script consider 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.

Note that the Run script assumes that the tcsh shell can be found in /bin . If this is not the case, its first line must be changed.


Things that are NOT in the installation files. 


For advanced users : how to make the installation files ?

Case 1 (source and tests) : you want to produce the file src_tests_x.x.x.tar.gz

Here, for example, we suppose that you have modified the code (in order to implement a new feature). This modification works, so it is time to synchronize with the main code. If the modifications are rather large, it is worthwhile to send your complete version to the ABINIT group.

Previously, you should have given a version number to your version. Simply modify the appropriate variable in the Makefile file of your ~local_ABINIT directory. Then issue

make new_version_number
to touch the few routines that need this version number, then
make allseq
as for the installation.

When you think everything can be frozen, you must issue

make src_tests
That's all ..

Case 2 (version for a specific platform) : e.g. you work on a SGI machine, and want to produce the file sgi_r10000_x.x.x.tar.gz

The requirements are : all executables (abinis, newsp and abinip) are working, and you have not erased one of the files needed for the tests, both sequential and parallel. Also, the version number is supposed correct (see above to modify it). In this case, simply issue :

make sgi_r10000
For the sequential version only, or the parallel version only, use
make sgi_r10000_seq
or
make sgi_r10000_par
For the other platforms, use the appropriate platform name, mentioned at the beginning of the present document, or obtained by typing
make help


page : Home | Calcul Intensif | Calcul ab initio

9 July 1999.
Responsable : Xavier Gonze < gonze@pcpm.ucl.ac.be>
Conception : Jean-Michel Beuken < beuken@pcpm.ucl.ac.be>