# ABINIT. New user guide

This file gives a beginner's introduction to the use of the ABINIT package.

##### Copyright (C) 1998-2009 ABINIT group (DCA,XG,RC)
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.txt .

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

### Contents of new user guide:

- 0. Foreword
- 1. Introduction
- 2. The sequential version of ABINIT : abinis
- 3. Other programs in the ABINIT package.
- 4. Input variables to abinit.
- 5. Output files.
- 6. What does the code do?

### 0. Foreword

The ABINIT package is written by the ABINIT group.

You will find the welcome message, and basic information about the Web site in the welcome address .

Before reading the present file, you should get some theoretical background. In case you have already used another electronic structure code, or a quantum chemistry code, it might be sufficient to read the introduction of the paper ``Iterative minimization techniques for ab initio total-energy calculations: molecular dynamics and conjugate gradients'' M. C. Payne, M. P. Teter, D. C. Allan, T. A. Arias, and J. D. Joannopoulos, Rev. Mod. Phys. 64, 1045-1097 (1992). If you have never used another electronic structure code or a Quantum Chemistry package, you should browse through the Chaps. 1 to 13 , and appendices L and M of the book Electronic Structure. Basic Theory and Practical Methods. R. M. Martin. Cambridge University Press (2004) ISBN 0 521 78285 6.

After having gone through this beginner's introduction, you should follow the tutorial.

### 1. Introduction

ABINIT is a package whose main program allows to find the total energy, charge density and electronic structure of systems made of electrons and nuclei (molecules and periodic solids) within Density Functional Theory, using pseudopotentials and a planewave basis, or augmented plane waves, or even wavelets. Some possibilities of ABINIT go beyond Density Functional Theory, i.e. the many-body perturbation theory (GW approximation) and Time-Dependent Density Functional Theory. ABINIT also includes options to optimize the geometry according to the DFT forces and stresses, or to perform molecular dynamics simulation using these forces, or to generate dynamical (vibrations - phonons) properties, dielectric properties, mechanical properties, thermodynamical properties, etc . In addition to the main ABINIT code, different utility programs are provided.

We will use the name ~abinit to refer to the directory that contains the ABINIT package. In practice, a version number is appended to this name, to give for example : abinit-5.3.3 . ~abinit contains different subdirectories. For example, the present file, as well as other descriptive files, should be found in ~abinit/doc/users . Other subdirectories will be described later.

### 2. The sequential version of ABINIT : abinis .

The main code exists in a sequential version, with the name abinis (ABINIT sequential), and in a parallel version, with the name abinip (ABINIT parallel). In the present new user's help file, we will suppose that the sequential version is used. After installation, it is present in the package as ~abinit/src/main/abinis .

To run abinis you need four things:

- (1) Access to the executable, abinis.
- (2) An input file.
- (3) A files file (list of file names in a file).
- (4) A pseudopotential input file for each kind of element in the unit cell.

With these items a job can be run.

The full list of input variables, all of which are provided in the single input file, is given in the ABINIT input variables file.
The detailed description of input variables is given in:

- Basic variables, VARBAS
- Developpement variables, VARDEV
- Geometry builder + symmetry related variables, VARGEO
- Ground-state calculation variables, VARGS
- GW variables, VARGW
- Files handling variables, VARFIL
- Parallelisation variables, VARPAR
- Projector-Augmented Wave variables, VARPAW
- Response Function variables, VARRF
- Structure optimization variables, VARRLX

A set of examples aimed at guiding the beginner is available in the tutorial.

Other test cases (more than 500 input files) can be found in the ~abinit/test subdirectories, especially fast, v1, v2, v3, v4, v5.

Many different sorts of pseudopotentials can be used with ABINIT. Most of them can be found on the ABINIT web site. There is a set of Teter hardness-conserving potentials, a set of Troullier-Martins potentials, a few Goedecker-Teter-Hutter pseudopotentials, and Hartwigsen-Goedecker-Hutter potentials for the whole periodic table. A subset of existing pseudopotentials are used for test cases, and are located in the ~abinit/tests/Psps_for_tests directory. Information on pseudopotential files can be found in the ABINIT help file and the ~abinit/doc/psp_infos directory.

### 3. Other programs in the ABINIT package.

In addition to abinit, there are utility programs.
mrgddb, anaddb, aim, conducti, optics, newsp, mrgscr, and cut3d are present in the package.

mrgddb and anaddb allow to post-process reponses to atomic displacements and/or to homogeneous electric field, and/or to strain perturbation, as generated by abinit, to produce full phonon band structures, thermodynamical functions, piezoelectric properties, superconducting properties, to name a few. "mrgddb" is for "Merge of Derivative DataBases", while "anaddb" is for "Analysis of Derivative DataBases".

Another utility is newsp, whose main routine source is called newsp.F90. It allows a crude interpolation among the wavefunctions at different k points and is useful in reformatting wavefunction files to restart jobs on either new unit cell geometries, new planewave cutoffs, or new k point grids. Most of its capabilities have been transferred a few years ago inside abinit, however.

cut3d can be used to post-process the three-dimensional density (or potential) files generated by abinit. It allows to deduce charge density in selected planes (for isodensity plots), along selected lines, or at selected points. It allows also to make the Hirshfeld decomposition of the charge density in "atomic" contributions.

aim is also a post-processor of the three-dimensional density files generated by abinit. It performs the Bader Atom-In-Molecule decomposition of the charge density in "atomic" contributions.

conducti allows to compute the frequency-dependent optical conductivity.

At the level of graphics, many commercial or free softwares can be used to visualize ABINIT outputs. Some indications are contained in the ~abinit/doc/tutorial/lesson_visual.txt file, but this topics has not yet been the subject of a systematic help file.

### 4. Input variables to abinit.

The ABINIT help file describes the input variables and the output file. As an overview, the most important input variables are listed below:

    acell(3)        lattice constant of periodic cell in Bohr.
    diemac          gives an indicative macroscopic dielectric constant, to ease convergence
                    (use 2.0 for atoms and small molecules; for small solid states systems, the default should be OK)
    ecut            planewave kinetic energy cutoff in Hartree
    ionmov          when ionmov = 0 : the ions and cell shape are fixed
                                = 2 : search for the equilibrium geometry
                                = 6 : molecular dynamics
    iscf            either a positive number for defining self-consistent
                    algorithm (usual), or -2 for band structure in fixed potential
    kptopt          option for specifying the k-point grid
                    if kptopt=1, automatic generation, using ngkpt and shiftk.
                    (for the latter, see the abinis_help file)
    natom           total number of atoms in unit cell
    ngkpt(3)        dimensions of the three-dimensional grid of k-points
    nstep           maximal number of self-consistent cycles (on the order of 20)
    ntime           number of molecular dynamics or relaxation steps
    ntypat          number of types of atoms
    occopt          set the occupation of electronic levels :
                     =1 for semiconductors
                     =3 ... 7  for metals
    optdriver       when == 3 and 4 : will do GW calculations (many-body perturbation theory)
    rfelfd          when /= 0 : will do response calculation to electric field
    rfphon          when = 1 : will do response calculation to atomic displacements
    rprim(3,3)      dimensionless primitive translations of periodic cell;
                    each COLUMN of this array is one primitive translation
    typat(natom)     sequence of integers, specifying the type of each atom.
                    NOTE: the atomic coordinates (xangst, xcart or xred)
                    must be specified in the same order
    tolmxf          force tolerance for structural relaxation in Hartree/Bohr
    tolvrs          tolerance on self-consistent convergence
    xangst(3,natom)  cartesian coordinates (Angstrom) of atoms in unit cell
                    NOTE: only used when "xred" and "xcart" are absent
    xcart(3,natom)  cartesian coordinates (Bohr) of atoms in unit cell
                    NOTE: only used when "xred" and "xangst" are absent
    xred(3,natom)   fractional coordinates for atomic locations;
                    NOTE: leave out if xangst or xcart is used
    znucl(ntypat)   Nuclear charge of each type of element; must agree with
                    nuclear charge found in psp file.

### 5. Output files.

Output from an abinis run shows up in several files and in the standard output. Usually one runs the command with a pipe of standard output to a log file, which can be inspected for warnings or error messages if anything goes wrong or otherwise can be discarded at the end of a run. The more easily readable formatted output goes to the output file whose name is given in the "files" file, i.e. you provide the name of the formatted output file. No error message is reported in the latter file. On the other hand, this is the file that is usually kept for archival purposes.

In addition, wavefunctions can be input (starting point) or output (result of the calculation), and possibly, charge density and/or electrostatic potential, if they have been asked for. These three sets of data are stored in unformatted files.
The Density Of States (DOS) can also be an output as a formatted (readable) file.
An analysis of geometry can also be provided (GEO file)
The name of these files is constructed from a "root" name, that must be different for input files and output files, and that is provided by the user, to which the code will append a descriptor, like WFK for wavefunctions, DEN for the density, POT for the potential, DOS for the density of states ...

There are also different temporary files. A "root" name should be provided by the user, from which the code generates a full name. Amongst these files, there is a "status" file, summarizing the current status of advancement of the code, in long jobs. ABINIT abinis_help contains more details.

### 6. What does the code do?

The simplest sort of job computes an electronic structure for a fixed set of atomic positions within a periodic unit cell. By electronic structure , we mean a set of eigenvalues and wavefunctions which achieve the lowest (DFT) energy possible for that basis set (that number of planewaves). The code takes the description of the unit cell and atomic positions and assembles a crystal potential from the input atomic pseudopotentials, then uses either an input wavefunction or simple gaussians to generate the initial charge density and screening potential, then uses a self-consistent algorithm to iteratively adjust the planewave coefficients until a sufficient convergence is reached in the energy.

Analytic derivatives of the energy with respect to atomic positions and unit cell primitive translations yield atomic forces and the stress tensor. The code can optionally adjust atomic positions to move the forces toward zero and adjust unit cell parameters to move toward zero stress. It can performs molecular dynamics. It can also be used to find responses to atomic displacements and homogeneous electric field, so that the full phonon band structure can be constructed...

In order to know more about ABINIT, please follow the Tutorial

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