Skip to content

gstate input variables

This document lists and provides the description of the name (keywords) of the gstate input variables to be used in the input file for the abinit executable.

algalch

Mnemonics: ALGorithm for generating ALCHemical pseudopotentials
Mentioned in topic(s): topic_AtomTypes
Variable type: integer
Dimensions: (ntypalch)
Default value: ntypalch * 1
Added in version: before_v9

Test list (click to open). Rarely used, [1/1245] in all abinit tests, [0/159] in abinit tutorials

Used for the generation of alchemical pseudopotentials, that is, when ntypalch is non-zero.

Give the algorithm to be used to generate the ntypalch alchemical potentials from the different %npspalch pseudopotentials dedicated to this use.

Presently, algalch can only have the value 1, that is:

  • the local potentials are mixed, thanks to the mixalch mixing coefficients
  • the form factors of the non-local projectors are all preserved, and all considered to generate the alchemical potential
  • the scalar coefficients of the non-local projectors are multiplied by the proportion of the corresponding type of atom that is present in mixalch
  • the characteristic radius for the core charge is a linear combination of the characteristic radii of the core charges, build with the mixalch mixing coefficients
  • the core charge function f(r/r_c) is a linear combination of the core charge functions, build with the mixalch mixing coefficients

Later, other algorithms for the mixing might be included.

Important

Note that alchemical mixing cannot be used with PAW.

auxc_ixc

Mnemonics: AUxiliary XC functional for hybrid functional, IXC number
Mentioned in topic(s): topic_Hybrids
Variable type: integer
Dimensions: scalar
Default value: 1
Added in version: before_v9

Test list (click to open). Rarely used, [1/1245] in all abinit tests, [0/159] in abinit tutorials

Specification of an auxiliary exchange-correlation functional, thanks to its ixc value, to possibly replace the heavy evaluation of an hybrid functional at specific occasions, e.g. when the Fock operator is frozen during the self-consistent cycle, thanks to fockoptmix == 11, or when evaluating the correction to forces due to the density residual. This auxiliary exchange- correlation functional might be rescaled, thanks to auxc_scal when fockoptmix == 11. If gwcalctyp == 5, 15 or 25, auxc_ixc refers to ixc_sigma instead of ixc.

auxc_scal

Mnemonics: AUxiliary XC functional for hybrid functional- SCALing factor
Mentioned in topic(s): topic_Hybrids
Variable type: real
Dimensions: scalar
Default value: 1.0
Added in version: before_v9

Test list (click to open). Rarely used, [1/1245] in all abinit tests, [0/159] in abinit tutorials

Possible scaling factor for the auxiliary exchange-correlation functional defined by auxc_ixc that has the goal to replace the Fock operator or hybrid functional when fockoptmix == 11.

The default value 1.0 corresponds to the unmodified xc functional. When the auxiliary functional is used to replace the hybrid functional in SCF loops, a value of 1.5 has been observed to speed up somehow the convergence.

boxcenter

Mnemonics: BOX CENTER
Mentioned in topic(s): topic_TDDFT
Variable type: real
Dimensions: (3)
Default value: [0.5, 0.5, 0.5]
Added in version: before_v9

Test list (click to open). Rarely used, [11/1245] in all abinit tests, [1/159] in abinit tutorials

Defines the center of the box, in reduced coordinates. At present, this information is only used in the case of Time-Dependent DFT computation of the oscillator strength. One must take boxcenter such as to be roughly the center of the cluster or molecule. The default is sensible when the vacuum surrounding the cluster or molecule has xred 0 or 1. On the contrary, when the cluster or molecule is close to the origin, it is better to take boxcenter = [0.0, 0.0, 0.0].

boxcutmin

Mnemonics: BOX CUT-off MINimum
Mentioned in topic(s): topic_Planewaves, topic_TuningSpeedMem
Variable type: real
Dimensions: scalar
Default value: 2.0
Added in version: before_v9

Test list (click to open). Moderately used, [29/1245] in all abinit tests, [10/159] in abinit tutorials

The box cutoff ratio is the ratio between the radius of the G-sphere that can be inserted in the FFT box (see ngfft) and the G-sphere used to represent the wavefunctions as computed from the input ecut. In order for the density to be exact (in the case of the plane wave part, not the PAW on-site terms), this ratio should be at least two.

Warning

If one uses a smaller ratio (e.g. 1.5), one will gain speed at the price of accuracy. Keep in mind that using a value of boxcutmin too close to 1 may lead to runtime errors in the FFT routines so a value larger than 1.1 is strongly recommended.

It should also be stressed that the quality of the forces is affected by the value of boxcutmin . The default value (2.0) is OK for ground state calculations and structural relaxations. On the contrary, the computations of vibrational frequencies based on finite-difference methods such as those implemented by phonopy turn out to be rather sensitive to the quality of the forces. Tests have shown that, for particular systems, phonopy calculations require a larger boxcutmin (e.g. 3.0) to reproduce the DFPT results. The optimal value of boxcutmin likely depends on the pseudopotentials and the system under investigation, yet this is something worth keeping in mind.

Note

Prior to v8.9, the use of boxcutmin for DFPT calculations was forbidden. However, after testing, it was seen that the deterioration in phonon band structures could be alleviated to a large extent by the imposition of the Acoustic Sum Rule asr.

cellcharge

Mnemonics: CELL CHARGE
Mentioned in topic(s): topic_Coulomb
Variable type: real
Dimensions: (nimage)
Default value: 0
*Added in version: v9.3.4

Test list (click to open). Moderately used, [13/1245] in all abinit tests, [7/159] in abinit tutorials

Used to establish charge balance between the number of electrons filling the bands and the nominal charge associated with the atomic cores. The code adds up the number of valence electrons provided by the pseudopotentials of each type (call this “zval”), then add cellcharge , to get the number of electrons per unit cell, %nelect. Then, if iscf is positive, the code adds up the band occupancies (given in array occ) for all bands at each k point, then multiplies by the k point weight wtk at each k point. Call this sum “nelect_occ” (for the number of electrons from occupation numbers). It is then required that: nelect_occ = %nelect. To treat a neutral system, which is desired in nearly all cases, one must use cellcharge = 0. To treat a system missing one electron per unit cell, set cellcharge = +1.

cellcharge superceeds the old charge input variable, whose name was rather unspecific.

When there are several images, cellcharge might depend on the image number, but ONLY when imgmov=6 and occopt=0 or 2. In the checking routine, %nelect is considered separately for each image, while in the remaining of the code, %nelect(1) is propagated, so that %nelect is still a scalar. This is consistent with the pSIC algorithm, see [Sadigh2015] and [Sadigh2015a].

charge

Mnemonics: CHARGE
Mentioned in topic(s): topic_Coulomb
Variable type: real
Dimensions: scalar
Default value: 0
Added in version: before_v9, obsolete

Test list (click to open). Moderately used, [66/1245] in all abinit tests, [12/159] in abinit tutorials

The charge input variable is obsolete, and has been replaced by cellcharge. It is still read during a transitional period, likely up to the end of v9 life cycle.

chkexit

Mnemonics: CHecK whether the user want to EXIT
Mentioned in topic(s): topic_Control
Variable type: integer
Dimensions: scalar
Default value: 0
Added in version: before_v9

Test list (click to open). Rarely used, [3/1245] in all abinit tests, [0/159] in abinit tutorials

If chkexit is 1 or 2, ABINIT will check whether the user wants to interrupt the run (using the keyword “exit” on the top of the input file or creating a file named “abinit.exit”: see the end of section 3.2 of the abinit help file).

  • 0 → the check is not performed at all
  • 1 → the check is not performed frequently (after each SCF step)
  • 2 → the check is performed frequently (after a few bands, at each k point)

In all cases, the check is performed at most every 2 seconds of CPU time.

chkparal

Mnemonics: CHecK whether the PARALelism is adequate
Mentioned in topic(s): topic_parallelism
Variable type: integer
Dimensions: scalar
Default value: 1
Added in version: before_v9

Test list (click to open). Rarely used, [1/1245] in all abinit tests, [0/159] in abinit tutorials

Not all parallelism types or level are allowed or simply relevant for the different optdriver values in ABINIT. It has been observed that some users do not understand well their relation. In particular, their expectation of the adequacy of some parallelism for some optdriver value was not correct, with a large loss of computing resources. Indeed, if the user does not sufficiently understand the parallelism in ABINIT, huge amount of ressources might be spend when they are booked for a run that cannot use these. Accordingly, the user might blame ABINIT for being slow while the user has simply not activated the relevant parallelism, or activated an irrelevant parallelism.

However, if the user correctly understand the parallelism, it might be more convenient to leave in the input file irrelevant variables. This is especially the case for high-throughput calculations driven by workflows developed for earlier versions of ABINIT.

The default value of chkparal , will enforce some basic relevance of the input variables related to parallelism, thus hopefully preventing some users to loose computing power.

The following relevances and adequacies are checked at present if chkparal =1 : the input variable autoparal is relevant only for optdriver=1 calculations (ground-state); the input variable paral_kgb is relevant only for optdriver=1 calculations (ground-state) or for optdriver=66 (Laczos-Sternheimer GW).

The relevance of paral_atom or paral_rf or gwpara is not checked at present. The default values should not yield loss of computing power.

chkprim

Mnemonics: CHecK whether the cell is PRIMitive
Mentioned in topic(s): topic_crystal, topic_UnitCell, topic_SmartSymm
Variable type: integer
Dimensions: scalar
Default value: 1
Added in version: before_v9

Test list (click to open). Moderately used, [85/1245] in all abinit tests, [8/159] in abinit tutorials

If the symmetry finder is used (see nsym), a non-zero value of chkprim will make the code stop if a non-primitive cell is used. If chkprim = 0, a warning is issued, but the run does not stop.

If you are generating the atomic and cell geometry using spgroup, you might generate a PRIMITIVE cell using brvltt = -1.

chksymbreak

Mnemonics: CHecK SYMmetry BREAKing
Characteristics: INPUT_ONLY
Mentioned in topic(s): topic_k-points
Variable type: integer
Dimensions: scalar
Default value: 1
Added in version: before_v9

Test list (click to open). Moderately used, [103/1245] in all abinit tests, [10/159] in abinit tutorials

This variable governs the behaviour of the code when there is a potential source of symmetry breaking related to the k point grid.

When chksymbreak = 1, the code stops if the k point grid is non-symmetric, in case kptopt =1, 2, or 4. Also, the code stops if nshiftk is not 1, 2 or 4.

Note that the check is disabled when the number of k-points in the BZ is greater than 40^3.

When chksymbreak = 0, there is no such check.

Explanation: In the ground-state calculation, such breaking of the symmetry is usually harmless. However, if the user is doing a calculation of phonons using DFPT (rfphon = 1), the convergence with respect to the number of k points will be worse with a non-symmetric grid than with a symmetric one.

So, it was decided to warn the user about such problem already at the level of the ground state calculations, although such warning might be irrelevant.

Concerning the values of nshiftk, usage of values other then 1, 2, or 4 can hardly be understood, as it will yield in many cases a non-homogeneous or non-symmetric k point grid. So, it is usually an error of the user.

If you encounter a problem outlined above, you have some choices: change your k point grid, to make it more symmetric, and/or respect nshiftk=1, 2, or 4, or ignore the problem, and set chksymbreak = 0.

chksymtnons

Mnemonics: CHecK SYMmetry of TNONS
Characteristics: INPUT_ONLY
Mentioned in topic(s): topic_crystal
Variable type: integer
Dimensions: scalar
Default value: 1
Added in version: 9.2.0

Test list (click to open). Moderately used, [74/1245] in all abinit tests, [4/159] in abinit tutorials

This variable governs the behaviour of the code when there is a potential symmetry breaking, related to the presence of non-symmorphic translations not leaving the FFT exchange-correlation grid invariant.

When chksymtnons = 1, the code stops if the non-symmorphic translation part of the symmetry operations has components that are not zero, or simple fractions with 2, 3, 4, 5, 6, 8, 9, 10 or 12 as denominators. Also, suggestions to bypass the problem are made in the output file.

When chksymtnons = 2, the code makes similar check, but does not stop after providing in the output file suggestions to bypass the problem.

When chksymtnons = 3, the code acts as with chksymtnons = 1, but then generates a FFT grid which is left invariant under the action of the spatial symmetry operations, which might enlarge it. In case of Constrained DFT calculations (see constraint_kind), only chksymtnons = 3 or chksymtnons = 0 are allowed.

When chksymtnons = 0, the code skips the check.

Explanation: In ground-state or DFPT calculations, such breaking of the symmetry is harmless. However, for a GW, BSE or cDFT calculation, the presence of non-symmorphic translations that are not coherent with the FFT grid will cause problems (e.g. enormous memory reservation, inducing segfault, or lack of convergence).

For cDFT calculations, the local integral of magnetization or charge is evaluated in real space, on the FFT grid. So, if the grids are locally different for two atoms related by symmetry (so in principle equivalent), there is a incoherency, that might induce lack of convergence.

In the GW or BSE parts of ABINIT, one needs to reconstruct the wavefunctions in the full Brillouin zone for calculating both the polarizability and the self-energy. The wavefunctions in the full Brillouin zone are obtained from the irreducible wedge by applying the symmetry operations of the space group of the crystal. In the present implementation, the symmetrisation of the wavefunctions is done in real space on the FFT mesh that, therefore, has to be coherent both with the rotational part as well as with the fractional translation of each symmetry operation. If the condition above (2, 3, 4, 5, 6, 7, 8, 9, 10, or 12 as denominator) is not met, the GW/BSE code will not be able to find a symmetry preserving FFT mesh.

So, it was decided to warn the user about such problem already at the level of the ground-state calculations, although such warning might be irrelevant.

If you encounter the problem outlined above, you have two choices: change your atomic positions (translate them) such that the origin appears as the most symmetric point; or ignore the problem, and set chksymtnons = 2 or 0 (only the latter for cDFT).. If chksymtnons = 2, ABINIT makes a suggestion of a possible global translation, and corresponding translated atomic positions.

chrgat

Mnemonics: CHARGE of the AToms
Mentioned in topic(s): topic_ConstrainedDFT
Variable type: real
Dimensions: [ natrd ] if natrd<natom, [ natom ] otherwise.

Default value: 0.0
Added in version: before_v9

Test list (click to open). Rarely used, [7/1245] in all abinit tests, [0/159] in abinit tutorials

Gives the target integrated charge in case of constrained DFT calculations, see constraint_kind. Given in atomic unit of charge (=minus the charge of the electron). Note that this number is the net positive charge inside the sphere: one subtract from the nucleus charge %ziontypat the integrated valence electron density in a sphere defined by ratsph. The latter has indeed a negative value. Note that if the sphere radius ratsph is not sufficiently large, the amount of electrons will be smaller than expected based on chemical intuition. This means that there is in this case a bias toward too positive integrated charges. By contrast, if the sphere radius is too large, the spheres will overlap, and the electrons in the interatomic region will be double counted.

constraint_kind

Mnemonics: CONSTRAINT KIND in constrained DFT
Mentioned in topic(s): topic_ConstrainedDFT
Variable type: integer
Dimensions: (ntypat)
Default value: 0
Only relevant if: iscf > 1 and iscf < 10 and ionmov /= 4
Added in version: before_v9

Test list (click to open). Rarely used, [12/1245] in all abinit tests, [0/159] in abinit tutorials

If constraint_kind is non-zero for at least one type of atom, the constrained DFT algorithm is activated. constraint_kind defines, for each type of atom, the kind of constraint(s) imposed by constrained DFT. When constraint_kind is zero for an atom type, there is not constraint applied to this atom type. Otherwise, different constraints can be imposed on the total charge (ion+electronic) and/or magnetization, computed inside a sphere of radius ratsph, possibly smeared within a width ratsm. Such integrated ion+electronic charge might be imposed to be equal to chrgat, while the magnetization might be compared to spinat. The first digit of constraint_kind defines the constraint on the charge, while the second digit defines the constraint on the magnetization.

When constraint_kind is 10 or above, the charge constraint will be imposed.

When constraint_kind =1 or 11, the exact value (vector in the non-collinear case, amplitude and sign in the collinear case) of the magnetization is constrained; When constraint_kind =2 or 12, only the magnetization axis is constrained (only meaningful in the non-collinear case, albeit allowed); When constraint_kind =3 or 13, only the magnetization magnitude is constrained. When constraint_kind =4 or 14, only the magnetization direction is constrained (only meaningful in the non-collinear case, not allowed in the collinear case);

For the algorithm, see topic_ConstrainedDFT. It makes important use of the potential residual, so the algorithm works only with iscf between 2 and 9. The balance between the potential residual, and the density/magnetization constraint is governed by magcon_lambda. The spherical integral is governed by ratsph and ratsm.

Note that while a spherical integral around an atom might reasonably well capture the magnetization of an atom within a solid or within a molecule, so that the sum of such magnetizations might be reasonably close to the total magnetization of the solid, such a procedure hardly gives the total charge of the solid: the space between the spheres is too large when the spheres do not overlap, while overlapping spheres will not deliver the correct total charge of the system.

Note that constraint_kind defines constraints for types of atoms, not for specific atoms. Atoms of the same type are supposed to incur the same constraint. If the user wants to impose different constraints on atoms of the same type (in principle), it is possible (and easy) to pretend that they belong to different types, even if the same pseudopotential file is used for these atoms. There is an example in test v8[24], the hydrogen dimer, where the charge around the first atom is constrained, and the charge around the second atom is left free.

Similarly, ABINIT is more careful about the control of symmetry: supposing that two atoms are related by some symmetry, then ABINIT generates a FFT grid that is invariant under that symmetry, unless this additional constraint on the FFT grid is explicitly suppressed by the user. In this respect, the default value of chksymtnons is not allowed, but chksymtnons must be equal to 3 (with the generation of a symmetric FFT grid) or 0.

The difference between constraint_kind =4 or 14 and constraint_kind =2 or 12 lies in the fact that constraint_kind =2 or 12 will consider similarly a magnetization vector and its opposite, as this constraint is just alignment on an axis, while constraint_kind =4 or 14 enforces that the scalar product of the target magnetization direction (normalized vector) and the actual optimized magnetization direction (normalized vector) is positive.

Incidentally, ionmov==4 is not allowed in the present implementation of constrained DFT because the motion of atoms and simultaneous computation of constraints would be difficult to handle.

cprj_in_memory

Mnemonics: C-PRoJectors IN MEMORY
Characteristics: DEVELOP
Mentioned in topic(s): topic_TuningSpeedMem
Variable type: integer
Dimensions: scalar
Default value: 0
Added in version:

Test list (click to open). Moderately used, [21/1245] in all abinit tests, [0/159] in abinit tutorials

For systems with many atoms, non-local operations are the most time-consuming part of the computation. The non-local contribution of the wavefunction \psi to the energy writes:

E_{non-local} = \sum_a\sum_{i,j} <\psi|p_{a,i}> e_{a,ij} <p_{a,j}|\psi>

and the Hamiltonian applied to a wavefunction is:

H_{non-local}|\psi> = \sum_a\sum_{ij} |p_{a,i}> D_{a,ij} <p_{a,i}|\psi>

The index “a” stands for atoms (natom), while “i” and “j” indices run over the set of available projectors in the pseudo-potential. e_{a,ij} and D_{a,ij} are scalars. In the PAW formalism (%usepaw = 1), the overlap operator has the same structure than H_{non-local}. Introducing the “cprj” coefficients:

cprj(a,i) = <p_{a,i}|\psi>

the energy writes:

E_{non-local} = \sum_a\sum_{ij} \left(cprj(a,i)\right)^* e_{a,ij} cprj(a,j)

and the Hamiltonian becomes:

H_{non-local}|\psi> = \sum_a\sum_{i,j} |p_{a,i}> D_{a,ij} cprj(a,j)

With cprj_in_memory = 0, “cprj” coefficients are computed on-the-fly in many parts of the code, including ground-state computations. If cprj_in_memory = 1, “cprj” coefficients are computed and stored in memory at the diagonalization step. This option is available only for LOBPCG (wfoptalg=114) and Chebyshev filtering (wfoptalg=111). If cprj_in_memory = 2, “cprj” coefficients are stored in memory during the whole computation, and they evolve as the wavefunctions do. This feature is available only for wfoptalg=10.

cprj_in_memory > 0 is expected to be faster than cprj_in_memory = 0 for big systems (many atoms and/or many bands).

For now, cprj_in_memory = 1 is implemented only in the following context:

  • optdriver = 0 : ground-state computation. If optdriver/=0, cprj_in_memory is set to 0 automatically.

  • wfoptalg = 10,114 or 111 : using Congugate Gradient algorithm (PAW only), LOBPCG (PAW or NC) or Chebyshev filtering (PAW or NC)

  • rmm_diis = 0 : without the use of rmm_diis algorithm

  • berryopt = 0 : without finite electric-field

  • %usefock = 0 : without Fock exchange term in the functional

  • nucdipmom = 0 : without nuclear dipolar moments

For cprj_in_memory = 2, see cprj_update_lvl for a fine tuning of “cprj” updates (i.e. when they are computed directly from wavefunctions).

cpuh

Mnemonics: CPU time limit in Hours
Characteristics: NO_MULTI, INPUT_ONLY
Mentioned in topic(s): topic_Control
Variable type: real
Dimensions: scalar
Default value: 0.0
The use of this variable forbids the use of: cpum or cpus
Added in version: before_v9

Test list (click to open). Rarely used, [0/1245] in all abinit tests, [0/159] in abinit tutorials

Only one of the three real parameters cpus, cpum and cpuh can be defined in the input file to set up a CPU time limit. When the job reaches that limit, it will try to end smoothly. However, note that this might still take some time. If the user want a firm CPU time limit, the present parameter must be reduced sufficiently. Intuition about the actual margin to be taken into account should come with experience. A zero value has no action of the job.

Tip

One can pass the timelimit to abinit via the command line option:

abinit --timelimit hours:minutes:seconds

This approach is much more powerful especially when the job must be submitted to the queue via a submission script e.g. a Slurm script. In this case, indeed, one can define a shell variable for the time limit and use this variable to pass the time limit to Slurm and Abinit at the same time.

Use abinit --help for further information.

cpum

Mnemonics: CPU time limit in Minutes
Characteristics: NO_MULTI, INPUT_ONLY
Mentioned in topic(s): topic_Control
Variable type: real
Dimensions: scalar
Default value: 0.0
The use of this variable forbids the use of: cpuh or cpus
Added in version: before_v9

Test list (click to open). Rarely used, [0/1245] in all abinit tests, [0/159] in abinit tutorials

Only one of the three real parameters cpus, cpum and cpuh can be defined in the input file to set up a CPU time limit. When the job reaches that limit, it will try to end smoothly. However, note that this might still take some time. If the user want a firm CPU time limit, the present parameter must be reduced sufficiently. Intuition about the actual margin to be taken into account should come with experience. A zero value has no action of the job.

cpus

Mnemonics: CPU time limit in seconds
Characteristics: NO_MULTI, INPUT_ONLY
Mentioned in topic(s): topic_Control
Variable type: real
Dimensions: scalar
Default value: 0.0
The use of this variable forbids the use of: cpuh or cpum
Added in version: before_v9

Test list (click to open). Rarely used, [2/1245] in all abinit tests, [1/159] in abinit tutorials

Only one of the three real parameters cpus , cpum and cpuh can be defined in the input file to set up a CPU time limit. When the job reaches that limit, it will try to end smoothly. However, note that this might still take some time. If the user want a firm CPU time limit, the present parameter must be reduced sufficiently. Intuition about the actual margin to be taken into account should come with experience. A zero value has no action of the job.

diecut

Mnemonics: DIElectric matrix energy CUToff
Characteristics: ENERGY
Mentioned in topic(s): topic_SCFAlgorithms
Variable type: real
Dimensions: scalar
Default value: 2.2
Added in version: before_v9

Test list (click to open). Moderately used, [13/1245] in all abinit tests, [0/159] in abinit tutorials

Kinetic energy cutoff that controls the number of planewaves used to represent the dielectric matrix: (1/2) [ 2 \pi \GG_{diel,max}]^2 = diecut with \GG_{diel,max} being the maximum length of the reciprocal space planewave wavevectors for the dielectric matrix. Can be specified in Ha (the default), Ry, eV or Kelvin, since diecut has the ENERGY characteristics. (1 Ha = 27.2113845 eV) All planewaves inside this “basis sphere” centered at \GG=0 are included in the basis. This is useful only when iprcel > =21, which means that a preconditioning scheme based on the dielectric matrix is used.

NOTE: a negative diecut will define the same dielectric basis sphere as the corresponding positive value, but the FFT grid will be identical to the one used for the wavefunctions. The much smaller FFT grid, used when diecut is positive, gives exactly the same results.

No meaning for RF calculations yet.

diegap

Mnemonics: DIElectric matrix GAP
Characteristics: ENERGY
Mentioned in topic(s): topic_SCFAlgorithms
Variable type: real
Dimensions: scalar
Default value: 0.1
Added in version: before_v9

Test list (click to open). Rarely used, [8/1245] in all abinit tests, [0/159] in abinit tutorials

Gives a rough estimation of the dielectric gap between the highest energy level computed in the run, and the set of bands not represented. Used to extrapolate dielectric matrix when iprcel >= 21. Can be specified in Ha (the default), Ry, eV or Kelvin, since diegap has the ENERGY characteristics (1 Ha = 27.2113845 eV).

No meaning for RF calculations yet.

dielam

Mnemonics: DIElectric matrix LAMbda
Mentioned in topic(s): topic_SCFAlgorithms
Variable type: real
Dimensions: scalar
Default value: 0.5
Only relevant if: iprcel >= 21
Added in version: before_v9

Test list (click to open). Rarely used, [8/1245] in all abinit tests, [0/159] in abinit tutorials

Gives the amount of occupied states with mean energy given by the highest level computed in the run, included in the extrapolation of the dielectric matrix.

No meaning for RF calculations yet.

dielng

Mnemonics: model DIElectric screening LeNGth
Characteristics: LENGTH
Mentioned in topic(s): topic_SCFAlgorithms
Variable type: real
Dimensions: scalar
Default value: 1.0774841
Added in version: before_v9

Test list (click to open). Moderately used, [73/1245] in all abinit tests, [28/159] in abinit tutorials

Used for screening length (in Bohr) of the model dielectric function, diagonal in reciprocal space. By default, given in Bohr atomic units (1 Bohr=0.5291772108 Angstrom), although Angstrom can be specified, if preferred, since dielng has the LENGTH characteristics. This model dielectric function is as follows ({\bf K} being a wavevector):

\begin{equation} \epsilon({\bf K}) = \frac{ 1 + **dielng** ^2 {\bf K}^2 }{ \left( 1/[[diemac]] + **dielng** ^2 {\bf K}^2 \right) [[diemix]] } \nonumber \end{equation}

The inverse of this model dielectric function will be applied to the residual, to give the preconditioned change of potential. Right at {\bf K}=0, \epsilon({\bf K}) is imposed to be 1.

If the preconditioning were perfect, the change of potential would lead to an exceedingly fast solution of the self-consistency problem (two or three steps). The present model dielectric function is excellent for rather homogeneous unit cells. When {\bf K}->0, it tends to the macroscopic dielectric constant, eventually divided by the mixing factor diemix (or diemixmag for magnetization). For metals, simply put diemac to a very large value (10^6 is OK) The screening length dielng governs the length scale to go from the macroscopic regime to the microscopic regime, where it is known that the dielectric function should tend to 1. It is on the order of 1 Bohr for metals with medium density of states at the Fermi level, like Molybdenum, and for Silicon. For metals with a larger DOS at the Fermi level (like Iron), the screening will be more effective, so that dielng has to be decreased by a factor of 2-4. This works for GS and RF calculations.

diemac

Mnemonics: model DIElectric MACroscopic constant
Mentioned in topic(s): topic_SCFAlgorithms
Variable type: real
Dimensions: scalar
Default value: 1000000.0
Added in version: before_v9

Test list (click to open). Moderately used, [578/1245] in all abinit tests, [58/159] in abinit tutorials

A rough knowledge of the macroscopic dielectric constant diemac of the system is a useful help to speed-up the SCF procedure: a model dielectric function, see the keyword dielng, is used for that purpose. It is especially useful for speeding up the treatment of rather homogeneous unit cells.

Some hint: The value of diemac should usually be bigger than 1.0, on physical grounds.

  • For metals, simply put diemac to a very large value (the default 10^6 is OK)
  • For silicon, use 12.0. A similar value is likely to work well for other semiconductors
  • For wider gap insulators, use 2.0 … 4.0
  • For molecules in an otherwise empty big box, try 1.5 … 3.0

Systems that combine a highly polarisable part and some vacuum are rather badly treated by the model dielectric function. One has to use the “extrapolar” technique, activated by the input variable iprcel. In sufficiently homogeneous systems, you might have to experiment a bit to find the best diemac . If you let diemac to its default value, you might even never obtain the self-consistent convergence! For response function calculations, use the same values as for GS. The improvement in speed can be considerable for small (but non-zero) values of the wavevector.

diemix

Mnemonics: model DIElectric MIXing factor
Mentioned in topic(s): topic_SCFAlgorithms
Variable type: real
Dimensions: scalar
Default value: 1.0 if %usepaw == 0 or iprcel !=0, 0.7 if %usepaw == 1 or iprcel == 0, None otherwise.

Only relevant if: diemix >= 0.0 and diemix <= 1.0
Added in version: before_v9

Test list (click to open). Moderately used, [236/1245] in all abinit tests, [1/159] in abinit tutorials

Gives overall factor of the preconditioned residual density/potential to be transferred in the SCF cycle. It should be between 0.0 and 1.0.

If the model dielectric function were perfect, diemix should be 1.0. By contrast, if the model dielectric function does nothing (when diemac = 1.0 or dielng is larger than the size of the cell), diemix can be used to damp the amplifying factor inherent to the SCF loop. For molecules, a value on the order 0.5 or 0.33 is rather usual. When mod(iscf,10)=3, 4,5 or 7, diemix is only important at the few first iterations when anharmonic effects are important, since these schemes compute their own mixing factor for self-consistency. Also note that a different value of diemix can be used for the magnetization (see diemixmag).

diemixmag

Mnemonics: model DIElectric MIXing factor for the MAGgnetization
Mentioned in topic(s): topic_spinpolarisation
Variable type: real
Dimensions: scalar
Default value: diemix if 70 < iprcel and iprcel < 80, diemix if iprcel == 0, diemix if iscf<10, -diemix otherwise.

Added in version: before_v9

Test list (click to open). Moderately used, [15/1245] in all abinit tests, [0/159] in abinit tutorials

Gives overall factor of the preconditioned residual magnetization/magnetic field to be transferred in the SCF cycle (see diemix for further information). For the time being, apply only when the SCF mixing is done on the density (iscf > =10).

A negative value of diemixmag means that magnetization is only preconditioned by ABS( diemixmag ), without the use of any preconditioner.

When SCF cycle has some difficulties to converge, changing the value of diemixmag can have a positive effect. In particular diemixmag = -4 is a good choice (i.e. diemixmag = 4, no other preconditioner on magnetization).

dosdeltae

Mnemonics: DOS DELTA in Energy
Characteristics: ENERGY
Mentioned in topic(s): topic_printing, topic_ElecDOS
Variable type: real
Dimensions: scalar
Default value: 0.0
Added in version: before_v9

Test list (click to open). Rarely used, [2/1245] in all abinit tests, [0/159] in abinit tutorials

Defines the linear grid resolution (energy increment) to be used for the computation of the Density-Of-States, when prtdos is non-zero. If dosdeltae is set to zero (the default value), the actual increment is 0.001 Ha if prtdos = 1 or 4 (smearing technique), and the much smaller value 0.00005 Ha if prtdos = 2, 3 or 5 (tetrahedron technique). This different default value arises because the smearing technique gives a quite smooth DOS, while the DOS from the tetrahedron method is rapidly varying.

enunit

Mnemonics: ENergy UNITs
Mentioned in topic(s): topic_Output, topic_ElecBandStructure
Variable type: integer
Dimensions: scalar
Default value: 0
Added in version: before_v9

Test list (click to open). Moderately used, [259/1245] in all abinit tests, [14/159] in abinit tutorials

Governs the units to be used for output of eigenvalues (and if any, phonon frequencies)

  • 0 → print eigenvalues in hartree;
  • 1 → print eigenvalues in eV;
  • 2 → print eigenvalues in both hartree and eV.

If phonon frequencies are to be computed:

  • 0 → phonon frequencies in Hartree and cm-1;
  • 1 → phonon frequencies in eV and THz;
  • 2 → phonon frequencies in hartree, eV, cm-1, Thz and Kelvin.

expert_user

Mnemonics: EXPERTise of the USER
Mentioned in topic(s): topic_UnitCell, topic_crystal, topic_SmartSymm, topic_GeoOpt, topic_k-points
Variable type: integer
Dimensions: scalar
Default value: 0
Added in version: 9.2.2

Test list (click to open). Rarely used, [3/1245] in all abinit tests, [0/159] in abinit tutorials

If set to 0, the checking provided by ABINIT is maximum (default values of chkprim, chksymbreak, chksymtnons, chkdilatmx, chkparal). If non-zero (up to three), the above-mentioned checking input variables are all disabled (set to zero) although it is still possible to activate particular tests by specifying input variables directly in the input file. In the future, the level three will always be the maximum allowed value, with all checks set to zero, while a more refined behaviour might be implemented for expert_user ==1 or 2).

extfpmd_nband

Mnemonics: EXTended FPMD: Number of Bands
Mentioned in topic(s): topic_ExtFPMD
Variable type: integer
Dimensions: scalar
Default value: 0
Added in version: 10.1.0

Test list (click to open). Rarely used, [1/1245] in all abinit tests, [0/159] in abinit tutorials

Specifies the number of bands to use for extended First-Principles Molecular Dynamics contributions when using useextfpmd = 5. This acts like nband for a conventional calculation. extfpmd_nband must be sufficiently high so that its occupancy is close to zero. Extended FPMD contributions will be computed from nband to extfpmd_nband .

extfpmd_nband must be greater than nband.

extfpmd_nbcut

Mnemonics: EXTended FPMD: Number of Bands at CUT
Mentioned in topic(s): topic_ExtFPMD
Variable type: integer
Dimensions: scalar
Default value: 25
Added in version: 9.5.2

Test list (click to open). Rarely used, [1/1245] in all abinit tests, [0/159] in abinit tutorials

Specifies the number of bands to use when averaging over last bands to get the energy shift when useextfpmd = 2 or 3.

extfpmd_nbcut must be less than or equal to nband.

extfpmd_nbdbuf

Mnemonics: EXTended FPMD: Number of BanDs for the BUFfer
Mentioned in topic(s): topic_ExtFPMD
Variable type: integer
Dimensions: scalar
Default value: 0
Added in version: 9.9.0

Test list (click to open). Rarely used, [1/1245] in all abinit tests, [0/159] in abinit tutorials

Specifies the number of bands to use for the buffer when useextfpmd /= 0. Among the total number of bands nband, last extfpmd_nbdbuf bands occupation will be set to 0, and ExtFPMD model will take charge of computing electronic contributions starting from nband - extfpmd_nbdbuf .

In some cases, setting this input variable to a positive number can solve convergency problems due to high variations of electron density within the SCF cycle.

extfpmd_nbdbuf must be less than or equal to nband.

fband

Mnemonics: Factor for the number of BANDs
Characteristics: INPUT_ONLY
Mentioned in topic(s): topic_BandOcc
Variable type: real
Dimensions: scalar
Default value: 0.125 if occopt == 1, 0.5 if occopt > 2, 0.0 if usewvl == 1, 0.0 otherwise.

Added in version: before_v9

Test list (click to open). Rarely used, [3/1245] in all abinit tests, [0/159] in abinit tutorials

Governs the number of bands to be used in the code in the case the parameter nband is not defined in the input file (which means that occopt is not equal to 0 or 2).

In case fband is 0.0, the code computes from the pseudopotential files and the geometry data contained in the input file, the number of electrons present in the system. Then, it computes the minimum number of bands that can accommodate them, and use that value for nband.

In case fband differs from zero, other bands will be added, just larger than fband times the number of atoms. This parameter is not echoed in the top of the main output file, but only the parameter nband that it allowed to compute. It is also not present in the dtset array (no internal). The default values are chosen such as to give naturally some conduction bands. This improves the robustness of the code, since this allows one to identify lack of convergence coming from (near-)degeneracies at the Fermi level. In the metallic case, the number of bands generated might be too small if the smearing factor is large. The occupation numbers of the higher bands should be small enough such as to neglect higher bands. It is difficult to automate this, so a fixed default value has been chosen.

fock_icutcoul

Mnemonics: Integer that governs the CUT-off for COULomb interaction
Mentioned in topic(s): topic_Hybrids, topic_Coulomb
Variable type: integer
Dimensions: scalar
Default value: 3
Added in version: before_v9

Test list (click to open). Rarely used, [0/1245] in all abinit tests, [0/159] in abinit tutorials

!!!Under development!!! Electronic structure calculations for isolated systems, 1D and 2D systems present a slow convergence with respect to the size of the supercell due to the long ranged Coulomb interaction and the high degree of non-locality of the operators involved. Thus, restricting the range of the Coulomb interaction, in order to prevent supercell images to interact can significantly speed-up convergence, or even can make convergence happen. Also, even in the ground-state case, a cut-off Coulomb interaction might prove useful.

fock_icutcoul defines the particular expression to be used for the Fock operator in reciprocal space (see icutcoul for the Hartree contributions to ground state calculations, and gw_icutcoul for the corresponding treatment in GW calculations).

The choice of fock_icutcoul depends on the dimensionality and the character of the XC functional used (or otherwise the presence of the exclusive treatment of the short-range exchange interaction). Possible values of fock_icutcoul are from 0 to 5, but currently are available options 0 and 5. Option 5 is hard coded as the method to be applied to HSE functionals.

Like for icutcoul, for 1-dimensional and 2-dimensional systems, the geometry of the system has to be specified explicitly. This is done thanks to vcutgeo. For 0-, 1- and 2-dimensional systems, a cut-off length has to be provided, thanks to rcut.

  • 0 → Sphere (molecules, but also 3D-crystals, see below). See rcut.
  • 1 → (W.I.P.) cylinder (nanowires, nanotubes). See vcutgeo and rcut.
  • 2 → (W.I.P) Surface. See vcutgeo and rcut.
  • 3 → (W.I.P) 3D crystal (Coulomb interaction without cut-off).
  • 4 → (W.I.P.)ERF, long-range only Coulomb interaction.
  • 5 → ERFC, short-range only Coulomb interaction (e.g. as used in the HSE functional).

Note that Spencer and Alavi showed that the spherical cutoff can efficiently be used also for 3D systems [Spencer2008]. In the latter case, use a negative value for the cutoff radius of the sphere (rcut<0), which is automatically calculated so that the volume enclosed in the sphere is equal to the volume of the solid.

fockdownsampling

Mnemonics: FOCK operator, k-grid DOWNSAMPLING
Mentioned in topic(s): topic_Hybrids
Variable type: integer
Dimensions: (3)
Default value: 3*1
Only relevant if: %usefock == 1
Added in version: before_v9

Test list (click to open). Rarely used, [10/1245] in all abinit tests, [0/159] in abinit tutorials

The k wavevector grid used to compute the Fock operator in the full Brillouin Zone might be a subset of the full Brillouin Zone of the k point grid used for the wavefunctions (see kptopt for its definition). fockdownsampling allows one to define such a reduced set of k wavevectors, yielding a significant speed up at the expense (possibly) of accuracy. The final grid has nkpthf k points, with coordinates %kptns_hf.

In the simplest case, the three values of fockdownsampling are equal, and simply gives the factor by which the initial k point grid will be downsampled along every direction. If fockdownsampling is 3*1, the sampling for the Fock operator is the same as the sampling for the wavefunctions. If fockdownsampling is 3*2 the sampling will have 8 times less k points. Conventionally, if fockdownsampling is 3*0, then the Fock operator is obtained solely from the Gamma point. Also, as soon as fockdownsampling is not 3*1 or 3*0, the k point grid from which a subset will be taken is obtained by imposing nshiftk = 1.

A more accurate description is now given, as one can achieve a better control than described above, with differing values of fockdownsampling and also with negative numbers. One starts from the k point grid defined by kptrlatt, with nshiftk = 1. The absolute value of each of the three numbers of fockdownsampling is used to sample the corresponding axis (in reduced coordinate), as described above. Moreover, the obtained k grid might even be further downsampled by specifying negative numbers: if all three are negative, one further downsamples each 2x2x2 subset of k points by taking its FCC subset (so, 4 points instead of 8); if two are negative, one downsamples each 2x2x2 subset of k points by taking its BCC subset (so, 2 points instead of 8); is only one is negative, then the two other axes are sampled using a face-centered sampling. Finally, some of the values might be taken as 0, in which case the corresponding direction is sampled by only one layer of points (if two are zero, a line of points is obtained).

fockoptmix

Mnemonics: FOCK operator: OPTions for MIXing
Mentioned in topic(s): topic_Hybrids
Variable type: integer
Dimensions: scalar
Default value: 0
Only relevant if: %usefock == 1
Added in version: before_v9

Test list (click to open). Rarely used, [6/1245] in all abinit tests, [0/159] in abinit tutorials

Governs the mixing algorithm at the level of the Fock operator, i.e. how to mix it, and how the underlying SCF calculation is to be performed. It is the most relevant when the Fock operator is not updated at each SCF step (nnsclohf/=0).

The last digit of fockoptmix governs what happens at the level of the SCF algorithm, when the Fock operator is updated.

  1. If fockoptmix == 0: the SCF algorithm is not restarted (it continues to use the previous potential/density pairs without worrying).
  2. If fockoptmix == 1: the SCF algorithm is restarted (the previous potential/density pairs are discarded).

The second-to-last (tens) digit governs the possible modification of the XC functional inside the SCF loop to take into account the lack of update of the Fock operator. Irrelevant when the unit digit is 0. If the value 1 is used (so, e.g. fockoptmix == 11), an auxiliary xc functional is used inside the SCF loop, for a frozen ACE Fock operator. This auxiliary functional is specified thanks to auxc_ixc and auxc_scal.

The third-to-last (hundreds) digit governs the mixing of the Fock operator itself with its previous occurrences. Irrelevant when the unit digit is 0.

hyb_mixing

Mnemonics: HYBrid MIXING coefficient for unscreened fock operator
Mentioned in topic(s): topic_Hybrids
Variable type: real
Dimensions: scalar
Default value: -999.0
Comment: With the default, hyb_mixing is initialized from ixc.
Only relevant if: %usefock > 0
Added in version: before_v9

Test list (click to open). Rarely used, [5/1245] in all abinit tests, [0/159] in abinit tutorials

Mixing coefficient for the unscreened Fock operator in case of hybrid functionals. Hartree-Fock corresponds to 1.0, PBE0 to 0.25, and B3LYP to 0.2.

ABINIT knows the correct value from ixc. Experts might nevertheless tune this mixing coefficient.

hyb_mixing_sr

Mnemonics: HYBrid MIXING coefficient for Short-Range screened fock operator
Mentioned in topic(s): topic_Hybrids
Variable type: real
Dimensions: scalar
Default value: -999.0
Comment: With the default, hyb_mixing_sr is initialized from ixc.
Only relevant if: %usefock > 0
Added in version: before_v9

Test list (click to open). Rarely used, [3/1245] in all abinit tests, [0/159] in abinit tutorials

Mixing coefficient for the screened Fock operator in case of hybrid functionals. HSE has 0.25.

ABINIT knows the correct value from ixc. Experts might nevertheless tune this mixing coefficient.

hyb_range_dft

Mnemonics: HYBrid RANGE for the DFT leftover from the screened fock operator
Mentioned in topic(s): topic_Hybrids
Variable type: real
Dimensions: scalar
Default value: -999.0 or hyb_range_fock if it is defined by the user
Comment: With the default=-999.0, hyb_range_dft is initialized from ixc.
Only relevant if: %usefock > 0
Added in version: before_v9

Test list (click to open). Rarely used, [2/1245] in all abinit tests, [0/159] in abinit tutorials

Range of the DFT leftover from the screened Fock operator in case of hybrid functionals (actually, coefficient of the distance appearing in the erf function, thus it has the dimension of an inverse distance).

As described in the LibXC sources (and copied in the ABINIT doc, see ixc = -428), there is a mess due to an error in the original publication. ABINIT knows the LibXC value from ixc, that might not agree with the definitions from other codes. Usually, hyb_range_dft is the same as hyb_range_fock, see the latter for the different values. However, there is a noticeable exception, the HSE03 from the original paper (not the HSE03 from VASP), for which hyb_range_dft = 0.188988 while hyb_range_fock = 0.106066.

hyb_range_fock

Mnemonics: HYBrid RANGE for the screened FOCK operator
Mentioned in topic(s): topic_Hybrids
Variable type: real
Dimensions: scalar
Default value: -999.0 or hyb_range_dft if it is defined by the user
Comment: With the default=-999.0, hyb_range_fock is initialized from ixc.
Only relevant if: %usefock > 0
Added in version: before_v9

Test list (click to open). Rarely used, [2/1245] in all abinit tests, [0/159] in abinit tutorials

Range of the screened Fock operator in case of hybrid functionals (actually, coefficient of the distance appearing in the erf function, thus it has the dimension of an inverse distance).

As described in the LibXC sources (and copied in the ABINIT doc, see ixc = -428), there is a mess due to an error in the original publication. ABINIT knows the LibXC value from ixc, that might not agree with the definitions from other codes. Usually, hyb_range_dft is the same as hyb_range_fock , with one exception explained in hyb_range_dft. The HSE06 value from LibCX is 0.11, the one of Quantum Espresso is 0.106, the one of VASP is 0.105835 (=0.2 \AA^{-1}). The HSE03 value from LibCX is 0.106066 (=0.15/\sqrt{2})), the one of VASP is 0.1587531 (=0.3 \AA^{-1}).

iatsph

Mnemonics: Index for the ATomic SPHeres of the atom-projected density-of-states
Mentioned in topic(s): topic_printing, topic_ElecBandStructure, topic_ElecDOS, topic_AtomCentered
Variable type: integer
Dimensions: (natsph)
Default value: [ 1 … natsph ]
Only relevant if: prtdos == 3 or 4 or pawfatbnd in [1,2]
Added in version: before_v9

Test list (click to open). Rarely used, [9/1245] in all abinit tests, [2/159] in abinit tutorials

iatsph gives the number of the natsph atoms around which the sphere for atom-projected density-of-states will be build, in the prtdos = 3 or 4 cases. The radius of these spheres is given by ratsph. If pawfatbnd = 1 or 2, it gives the number of the natsph atoms around which atom-projected band structure will be built.

icoulomb

Mnemonics: Index for the COULOMB treatment
Mentioned in topic(s): topic_Coulomb
Variable type: integer
Dimensions: scalar
Default value: 0
Added in version: before_v9

Test list (click to open). Moderately used, [33/1245] in all abinit tests, [9/159] in abinit tutorials

Defines the type of computation (reciprocal space or real space) used for Hartree potential, local part of pseudo-potential and ion-ion interaction:

  • icoulomb = 0: usual reciprocal space computation, using icutcoul, gw_icutcoul and fock_icutcoul to define the Hartree potential, and using Ewald correction.
  • icoulomb = 1: free boundary conditions are used when the Hartree potential is computed, real space expressions of pseudo-potentials are involved (restricted to GTH pseudo-potentials) and simple coulomb interaction gives the ion-ion energy. The wavelet Coulomb solver is used in this case.

icutcoul

Mnemonics: Integer that governs the CUT-off for COULomb interaction
Mentioned in topic(s): topic_Coulomb
Variable type: integer
Dimensions: scalar
Default value: 3
Added in version: before_v9

Test list (click to open). Moderately used, [77/1245] in all abinit tests, [4/159] in abinit tutorials

Electronic structure calculations for isolated systems, 1D and 2D systems present a slow convergence with respect to the size of the supercell due to the long ranged Coulomb interaction and the high degree of non-locality of the operators involved. Thus, restricting the range of the Coulomb interaction, in order to prevent supercell images to interact can significantly speed-up convergence, or even can make convergence happen. Also, even in the ground-state case, a cut-off Coulomb interaction might prove useful.

icutcoul defines the particular expression to be used for the Coulomb-like terms in reciprocal space in ground-state calculations. See gw_icutcoul for GW calculationts, and fock_icutcoul for the Fock-like terms in ground-state calculations -e.g. using hybrid functionals-.

The choice of icutcoul depends on the dimensionality of the system. Possible values of icutcoul are from 0 to 5. For 1-dimensional and 2-dimensional systems, the geometry of the system (along which directions the cell is to be periodically repeated, along which ones the system is finite) has to be specified explicitly. This is done thanks to vcutgeo. For 0-, 1- and 2-dimensional systems, a cut-off length might be provided, depending on the methodology, thanks to rcut.

  • 0 → Sphere (molecules, but also 3D-crystals, see below). See rcut.
  • 1 → (W.I.P.) cylinder (nanowires, nanotubes). See vcutgeo and rcut.
  • 2 → Surface. See vcutgeo and rcut.
  • 3 → 3D crystal (Coulomb interaction without cut-off).
  • 4 → ERF, long-range only Coulomb interaction.
  • 5 → ERFC, short-range only Coulomb interaction (e.g. as used in the HSE functional). (W.I.P.)

Note that Spencer and Alavi showed that the spherical cutoff can efficiently be used also for 3D systems [Spencer2008]. In the latter case, use a negative value for the cutoff radius of the sphere (rcut<0), which is automatically calculated so that the volume enclosed in the sphere is equal to the volume of the solid.

iprcel

Mnemonics: Integer for PReConditioning of ELectron response
Mentioned in topic(s): topic_SCFAlgorithms
Variable type: integer
Dimensions: scalar
Default value: 0
Added in version: before_v9

Test list (click to open). Moderately used, [27/1245] in all abinit tests, [3/159] in abinit tutorials

Used when iscf > 0, to define the SCF preconditioning scheme. Potential- based preconditioning schemes for the SCF loop (electronic part) are still a subject of active research. The present parameter (electronic part) describes the way the change of potential is derived from the residual. The possible values of iprcel correspond to:

  • 0 → model dielectric function described by diemac, dielng and diemix.
  • larger or equal to 21 → will compute the dielectric matrix according to diecut, dielam, diegap. This methodology is described in [Anglade2008].
  • Between 21 and 29 → for the first few steps uses the same as option 0 then compute RPA dielectric function, and use it as such.
  • Between 31 and 39 → for the first few steps uses the same as option 0 then compute RPA dielectric function, and use it, with the mixing factor diemix.
  • Between 41 and 49 → compute the RPA dielectric matrix at the first step, and recompute it at a later step, and take into account the mixing factor diemix.
  • Between 51 and 59 → same as between 41 and 49, but compute the RPA dielectric matrix by another mean
  • Between 61 and 69 → same as between 41 and 49, but compute the electronic dielectric matrix instead of the RPA one.
  • Between 71 and 78 → STILL UNDER DEVELOPMENT – NOT USABLE; Use the modified Kerker preconditioner with a real-space formulation (basic formulation is shown at dielng). The dielectric matrix is approximated thanks to diemac and dielng. Note that diemix is also used.
  • 79 → STILL UNDER DEVELOPMENT – NOT USABLE; same as previous but with an alternate algorithm.
  • 141 to 169 → same as Between 41 and 69 (but, the dielectric matrix is also recomputed every iprcel modulo 10 step).

The computation of the dielectric matrix (for 0 [100]< iprcel < 70 [100]) is based on the extrapolar approximation, see [Anglade2008]. This approximation can be tuned with diecut, dielam, and diegap. Yet its accuracy mainly depends on the number of conduction bands included in the system. Having 2 to 10 empty bands in the calculation is usually enough (use nband).

NOTES:

  • The step at which the dielectric matrix is computed or recomputed is determined by modulo( iprcel ,10). The recomputation happens just once in the calculation for iprcel < 100.
  • For non-homogeneous relatively large cells iprcel = 45 will likely give a large improvement over iprcel = 0.
  • In case of PAW and iprcel > 0, see pawsushat input variable. By default, an approximation (which can be suppressed) is done for the computation of susceptibility matrix.
  • For extremely large inhomogeneous cells where computation of the full dielectric matrix takes too many weeks, 70 < iprcel < 80 is advised.
  • For nsppol = 2 or nspinor = 2 with metallic occopt, only mod(iprcel,100) <50 is allowed.
  • No meaning for RF calculations yet.
  • The exchange term in the full dielectric matrix diverges for vanishing densities. Therefore the values of iprcel beyond 60 must not be used for cells containing vacuum, unless ones computes this matrix for every step ( iprcel = 161).

iqpt

Mnemonics: Index for QPoinT generation
Characteristics: INPUT_ONLY
Mentioned in topic(s): topic_q-points
Variable type: integer
Dimensions: scalar
Default value: 0
Added in version: before_v9

Test list (click to open). Rarely used, [12/1245] in all abinit tests, [4/159] in abinit tutorials

Only used if nqpt = 1, and qptopt = 1 to 4.

Defines the index of the Q point to be selected in the list of q points generated by ngqpt, qptrlatt, nshiftq, and shiftq.

If iqpt = 0, then the q point is Gamma (0 0 0).

The usual working mode is to define a series of values for iqpt , starting with iqpt = 0 or 1 (so through the definition of iqpt: ), and increasing it by one for each dataset (thanks to iqpt+ ).

ivalence

Mnemonics: Index of the highest VALENCE band
Characteristics: INPUT_ONLY
Mentioned in topic(s): topic_BandOcc, topic_DeltaSCF
Variable type: integer
Dimensions: scalar
Default value: 0
Added in version: v9

Test list (click to open). Rarely used, [3/1245] in all abinit tests, [0/159] in abinit tutorials

Only used if [[occopt] = 9.

When occopt==9, the lowest ivalence bands are considered to be valence bands and nqfd holes are constrained to exist in them. Accordingly, higher energy bands (with index >= ivalence + 1) are considered to be conduction bands, and nqfd electrons are constrained there. See [Paillard2019] for more details about the general method implemented.

ixcpositron

Mnemonics: Integer for the eXchange-Correlation applied to the electron-POSITRON interaction
Mentioned in topic(s): topic_positron
Variable type: integer
Dimensions: scalar
Default value: 1
Comment: (Teter parameterization). However, if all the pseudopotentials have the same value of pspxc, the initial value of ixc will be that common value
Only relevant if: positron/=0
Added in version: before_v9

Test list (click to open). Rarely used, [10/1245] in all abinit tests, [7/159] in abinit tutorials

Relevant only when positron/=0. Define the type of electron-positron correlation that is used in case of a electron-positron two-component DFT calculation. Define also the analytical formula of the enhancement factor used to compute the electron-positron annihilation rate:

Electron-positron correlation functional:

Annihilation rate enhancement factor:

  • ixcpositron=1: Boronski and Nieminen full modelisation and RPA limit [Arponen1979a]
  • ixcpositron=11: Sterne and Kaiser [Boronski1986]
  • ixcpositron=2: Puska, Seitsonen and Nieminen [Sterne1991]
  • ixcpositron=3: Boronski and Nieminen full modelisation and RPA limit [Arponen1979a], with GGA corrections
  • ixcpositron=31: Sterne and Kaiser [Boronski1986], with GGA corrections

jellslab

Mnemonics: include a JELLium SLAB in the cell
Mentioned in topic(s): topic_Artificial
Variable type: integer
Dimensions: scalar
Default value: 0
Added in version: before_v9

Test list (click to open). Rarely used, [4/1245] in all abinit tests, [0/159] in abinit tutorials

If set to 1, a slab of uniform positive background charge density, that is, a jellium slab, is included in the calculation cell. A portion of the unit cell is filled with such positive charge density distribution which is equal to a bulk-mean value n_{bulk} between two edges and zero in the vacuum region if present. For the sake of convenience the unit cell is supposed to have the third crystal primitive lattice vector orthogonal to the other ones so that the portion of the cell filled by the jellium slab can be defined through its edges along z. The bulk-mean positive charge density is fixed by the input variable slabwsrad, while the position of the slab edges along z is defined through the input variables slabzbeg and slabzend.

kptbounds

Mnemonics: K PoinT BOUNDarieS
Characteristics: INPUT_ONLY
Mentioned in topic(s): topic_k-points, topic_ElecBandStructure
Variable type: real
Dimensions: (3,abs(kptopt)+1))
Default value: None
Added in version: before_v9

Test list (click to open). Moderately used, [19/1245] in all abinit tests, [8/159] in abinit tutorials

It is used to generate the circuit to be followed by the band structure, when kptopt is negative (it is not read if kptopt is zero or positive).

There are abs(kptopt) segments to be defined, each of which starting from the end point of the preceeding one. Thus, the number of points to be input is abs(kptopt)+1. They form a circuit starting at kptbounds (1:3,1)/kptnrm and ending at kptbounds (1:3,abs(kptopt)+1)/kptnrm. The number of divisions of each segment can be defined either using the array ndivk or the variable ndivsm (preferred) that just defines the number of divisions for the smallest segment.

As for kpt, kptbounds is specified using the primitive vectors in reciprocal space. If your Bravais lattice is simple, then it should be quite easy to find the coordinates of the end points. On the other hand, for centered, body-centered, face-centered, hexagonal, and rhombohedral Bravais lattice, the conversion might be more difficult. See the description of kpt for an explanation of how to convert data from the “conventional” cartesian coordinates to the primitive vectors in the reciprocal space. In order to help a bit, we list below a series of typical values, for the FCC, BCC, hexagonal and rhombohedral Bravais lattices. Note: all the data below are given in dimensionless units; they have to be rescaled by the actual lengths defined by the acell values. However, kptbounds values can be used as such, if the values of rprim given below are adopted.

A. FCC lattice

Suppose the primitive vectors in real space are given by

  rprim   0 1 1    1 0 1    1 1 0

or

  rprim   0 1/2 1/2    1/2 0 1/2    1/2 1/2 0

(these two possibilities only differ by a scaling factor, irrelevant for the definition of the k points in the primitive vectors in reciprocal space). Then, the reciprocal primitive vectors (in conventional cartesian coordinates) are

  (-1/2 1/2 1/2), (1/2 -1/2 1/2), (1/2 1/2 -1/2)

or

  (-1 1 1), (1 -1 1), (1 1 -1)

and, in both cases, the coordinates of several special points with respect to primitive vectors in reciprocal space are

  X (0   1/2 1/2)   (conventional cartesian coordinate 1/2 0 0)
  X'(1/2 1/2 1  )   (conventional cartesian coordinate 1/2 1/2 0)  (an other instance of X, in another Brillouin zone)
  L (1/2 1/2 1/2)   (conventional cartesian coordinate  1/4 1/4 1/4)
  L'(1/2 0   0  )   (conventional cartesian coordinate -1/4 1/4 1/4) (an other instance of L, on another face of the BZ)
  W (1/4 1/2 3/4)   (conventional cartesian coordinate 1/2 1/4 0)
  U (1/4 5/8 5/8)   (conventional cartesian coordinate 1/2 1/8 1/8)
  K (3/8 3/8 3/4)   (conventional cartesian coordinate 3/8 3/8 0)

Note that K is actually equivalent to U, by spatial and translational symmetry. So, if you want to specify a typical circuit, the following might do the work: L-Gamma-X-W-K,U-L-W-X-K,U-Gamma with

  kptbounds  1/2 0 0  0 0 0  0 1/2 1/2  1/4 1/2 3/4  3/8 3/8 3/4  1/2 1/2 1/2  1/4 1/2 3/4  1/2 1/2 1  3/8 3/8 3/4  0 0 0

The lengths of segments (this information is useful to draw the band structure, with the correct relative scale between special points) can be found using the conventional cartesian coordinates:

l(L-Gamma)=\sqrt{3}/4=0.433… \n l(Gamma-X)=1/2=0.5 \n l(X-W)=1/4=0.25 \n l(W-K)=\sqrt{2}/8=0.177… \n l(K-L)=\sqrt{6}/8=0.306… \n l(L-W)=\sqrt{2}/4=0.354… \n l(W-X)=1/4=0.25 \n l(X-K)=\sqrt{2}/8=0.177… \n l(K-Gamma)=3\sqrt{2}/8=0.530… \n

B. BCC lattice

Suppose the primitive vectors in real space are given by

  rprim  -1 1 1    1 -1 1    1 1 -1

(as for the FCC lattice, there is a scale invariance). Then, the reciprocal primitive vectors (in conventional cartesian coordinates) are (0 ½ ½), (½ 0 ½), and (½ ½ 0) and the coordinates of several special points with respect to primitive vectors in reciprocal space are

  H (-1/2 1/2 1/2)   (conventional cartesian coordinate 1/2 0 0)
  N ( 0   0   1/2)   (conventional cartesian coordinate 1/4 1/4 0)
  P ( 1/4 1/4 1/4)   (conventional cartesian coordinate 1/4 1/4 1/4)

So, if you want to specify a typical circuit, the following might do the work: Gamma-H-N-Gamma-P-N-P-H

  kptbounds  0 0 0  -1/2 1/2 1/2  0 0 1/2  0 0 0   1/4 1/4 1/4  0 0 1/2  1/4 1/4 1/4  -1/2 1/2 1/2

The lengths of segments (this information is useful to draw the band structure, with the correct relative scale between special points) can be found using the conventional cartesian coordinates:

l(Gamma-H)=1/2=0.5 \n l(H-N)=\sqrt{2}/4=0.354… \n l(N-Gamma)=\sqrt{2}/4=0.354… \n l(Gamma-P)=\sqrt{3}/4=0.433… \n l(P-N)=1/4=0.25 \n l(N-P)=1/4=0.25 \n l(P-H)=\sqrt{3}/4=0.433… \n

C. Hexagonal lattices

Suppose the primitive vectors in real space are given by

  rprim  1 0 0    -1/2 sqrt(0.75) 0    0 0 1

The coordinates of several special points with respect to primitive vectors in reciprocal space are

  M (1/2 0 0) or (0 1/2 0) or (-1/2 1/2 0)
  L (1/2 0 1/2) or (0 1/2 1/2) or (-1/2 1/2 1/2)
  K (1/3 1/3 0) or (2/3 -1/3 0) or (-1/3 2/3 0)
  H (1/3 1/3 1/2) or (2/3 -1/3 1/2) or (-1/3 2/3 1/2)
  A (0 0 1/2)

So, if you want to specify a typical circuit, the following might do the work: K-Gamma-M-K-H-A-L-H-L-M-Gamma-A

  kptbounds  1/3 1/3 0  0 0 0  1/2 0 0  1/3 1/3 0  1/3 1/3 1/2  0 0 1/2  1/2 0 1/2  1/3 1/3 1/2  1/2 0 1/2  1/2 0 0  0 0 0  0 0 1/2

In order to find the lengths of segments (this information is useful to draw the band structure, with the correct relative scale between special points) one needs to know the a and c lattice parameters. Also, in what follows, we omit the 2\pi factor sometimes present in the definition of the reciprocal space vectors. The reciprocal vectors are (1/a\: 1/(\sqrt{3}a)\: 0), (0\: 2/(\sqrt{3}a)\: 0), (0\: 0\: 1/c). The lengths of the above-mentioned segments can be computed as:

l(K-Gamma)=2/(3a)=0.666…/a \n l(Gamma-M)=1/(\sqrt{3}a)=0.577…/a \n l(M-K)=1/(3a)=0.333…/a \n l(K-H)=1/(2c)=0.5…/c \n l(H-A)=2/(3a)=0.666…/a \n l(A-L)=1/(\sqrt{3}a)=0.577…/a \n l(L-H)=1/(3a)=0.333…/a \n l(H-L)=1/(3a)=0.333…/a \n l(L-M)=1/(2c)=0.5…/c \n l(M-Gamma)=1/(\sqrt{3}a)=0.577…/a \n l(Gamma-A)=1/(2c)=0.5…/c \n

D. Rhombohedral lattices

Rhombohedral lattices are characterised by two parameters, the length of the primitive vectors, that we will denote a0, and the angle they form, \gamma. These can be directly input of ABINIT, as acell and angdeg

This will generate the primitive vectors in real space, with

  acell a0 a0 a0    and      rprim  a 0 c    -a/2 a*sqrt(0.75) c    -a/2 -a*sqrt(0.75) c

with,

  • a^2+c^2=1,
  • a^2=2/3(1-\cos(\gamma)),
  • c^2=1/3(1+2\cos(\gamma)),
  • (a/c)^2=2(1-\cos(\gamma))/(1+2\cos(\gamma)), and also
  • \cos(\gamma)=(1-(a/c)^2/2)/(1+(a/c)^2).

Alternatively, these values of rprim might directly be the input of ABINIT (then, the balance of the scaling factor might be adjusted between acell and rprim).

Unlike for the simple cubic, FCC, BCC, hexagonal (and some other) Bravais lattice, the topology of the Brillouin zone will depend on the \gamma (or a/c) value. We give below information concerning the case when \cos(\gamma) is positive, that is, (a/c)^2 lower than 2.

The coordinates of several special points with respect to primitive vectors in reciprocal space will not depend on the a/c ratio, but some others will depend on it. So, some care has to be exercised. Notations for the Brillouin Zone special points are the same as in [Gonze1990].

  L (1/2 0 0) or (0 1/2 0) or (0 0 1/2) (or with negative signs)
  T (1/2 1/2 1/2)
  X (1/2 1/2 0) or (1/2 0 1/2) or (0 1/2 1/2) (or with separate negative signs)
  W (5/6 - (a/c)^2/6, 1/2, 1/6 + (a/c)^2/6 ) = (1 0 -1)*(1-(a/c)^2/2)/3 + (1 1 1)/2
  U ( (1+(a/c)^2)/6, (8-(a/c)^2)/12, (8-(a/c)^2)/12 ) = (-1 1/2 1/2)*(1-(a/c)^2/2)/3 + (1 1 1)/2
  K (1 0 -1)*(1+(a/c)^2/4)/3

So, if you want to specify a typical circuit, the following might do the work (the representative points on lines of symmetry are indicated - there are sometimes more than one way to go from one point to another): X-V-K-Sigma- Gamma-Lambda-T-Q-W-Y-L-sigma-Gamma-sigma-X. The suggestion is to sample this path with the following coordinates for the special points X, Gamma, T, L, Gamma, X:

  kptbounds  1/2 0 -1/2   0 0 0    1/2 1/2 1/2  1 1/2 0   1 0 0  1 1/2 1/2

In order to find the lengths of segments (this information is useful to draw the band structure, with the correct relative scale between special points) one needs to know the a and c lattice parameters. Also, in what follows, we omit the 2\pi factor sometimes present in the definition of the reciprocal space vectors. The reciprocal vectors are ( 2/(3a)\: 0\: 1/(3c) ), ( -1/(3a)\: 1/(\sqrt{3}a)\: 1/(3c) ), ( -1/(3a)\: -1/(\sqrt{3}a)\: 1/(3c) ). The lengths of the above-mentioned segments can be computed as:

l(X-Gamma)=2/(\sqrt{3}a)=1.155…/a \n l(K-Gamma)=4(1+(a/c)^2/4)/(3\sqrt{3}a) \n l(Gamma-T)=1/(2c) \n l(T-L)=2/(\sqrt{3}a)=1.155…/a \n l(T-W)=4(1-(a/c)^2/2)/(3\sqrt{3}a) \n l(L-Gamma)=\sqrt{4/(a^2)+1/(c^2)}/3 \n l(Gamma-X)=2\sqrt{1/(a^2)+1/(c^2)}/3 \n

kptrlatt

Mnemonics: K - PoinTs grid: Real space LATTice
Mentioned in topic(s): topic_k-points
Variable type: integer
Dimensions: (3,3)
Default value: 0
*The use of this variable forbids the use of: ngkpt
Added in version: before_v9

Test list (click to open). Moderately used, [69/1245] in all abinit tests, [7/159] in abinit tutorials

This input variable is used only when kptopt is positive. It partially defines the k point grid. The other piece of information is contained in shiftk. kptrlatt cannot be used together with ngkpt.

The values kptrlatt (1:3,1), kptrlatt (1:3,2), kptrlatt (1:3,3) are the coordinates of three vectors in real space, expressed in the %rprimd coordinate system (reduced coordinates). They define a super-lattice in real space. The k point lattice is the reciprocal of this super-lattice, possibly shifted (see shiftk).

If neither ngkpt nor kptrlatt are defined, ABINIT will automatically generate a set of k point grids, and select the best combination of kptrlatt and shiftk that allows one to reach a sufficient value of kptrlen. See this latter variable for a complete description of this procedure.

kptrlen

Mnemonics: K - PoinTs grid: Real space LENgth
Mentioned in topic(s): topic_k-points
Variable type: real
Dimensions: scalar
Default value: 30.0
Added in version: before_v9

Test list (click to open). Moderately used, [18/1245] in all abinit tests, [1/159] in abinit tutorials

This input variable is used only when kptopt is positive and non-zero.

Preliminary explanation: The k point lattice defined by ngkpt or kptrlatt is used to perform integrations of periodic quantities in the Brillouin Zone, like the density or the kinetic energy. One can relate the error made by replacing the continuous integral by a sum over k point lattice to the Fourier transform of the periodic quantity. Erroneous contributions will appear only for the vectors in real space that belong to the reciprocal of the k point lattice, except the origin. Moreover, the expected size of these contributions usually decreases exponentially with the distance. So, the length of the smallest of these real space vectors is a measure of the accuracy of the k point grid.

When either ngkpt or kptrlatt is defined, kptrlen is not used as an input variable, but the length of the smallest vector will be placed in this variable, and echoed in the output file.

On the other hand, when neither ngkpt nor kptrlatt are defined, ABINIT will automatically generate a large set of possible k point grids, and select among this set, the grids that give a length of smallest vector LARGER than kptrlen , and among these grids, the one that, when used with kptopt = 1, reduces to the smallest number of k points. Note that this procedure can be time-consuming. It is worth doing it once for a given unit cell and set of symmetries, but not use this procedure by default. The best is then to set prtkpt = 1, in order to get a detailed analysis of the set of grids.

If some layer of vacuum is detected in the unit cell (see the input variable vacuum), the computation of kptrlen will ignore the dimension related to the direction perpendicular to the vacuum layer, and generate a bi- dimensional k point grid. If the system is confined in a tube, a one- dimensional k point grid will be generated. For a cluster, this procedure will only generate the Gamma point.

magcon_lambda

Mnemonics: MAGnetization CONstraint LAMBDA parameter
Mentioned in topic(s): topic_MagMom
Variable type: real
Dimensions: scalar
Default value: 0.01
Added in version: before_v9

Test list (click to open). Moderately used, [13/1245] in all abinit tests, [0/159] in abinit tutorials

This variable gives the amplitude of the penalty function imposed on the magnetization vectors on each atom (turned on with flag variable magconon=1 to 3). Typical values for magcon_lambda are 0.001 to 0.1. The SCF convergence will be difficult if magcon_lambda is too large. If magcon_lambda is too small, the penalty will not be very effective and it will give magnetization not close to the desired spinat target. In case of convergence problem, it can help to start with a small value of magcon_lambda and to increase it by reading the wavefunction obtained with a lower magcon_lambda value. See variable magconon for more details.

magconon

Mnemonics: turn MAGnetization CONstraint ON
Mentioned in topic(s): topic_MagMom
Variable type: integer
Dimensions: scalar
Default value: 0
Added in version: before_v9

Test list (click to open). Rarely used, [1/1245] in all abinit tests, [0/159] in abinit tutorials

Turns on the imposition of a constraint on the magnetization, using a penalty function. For each atom, the magnetization is calculated in a sphere (radius ratsph) and a penalty function is applied to bring it to the input values of spinat. The constraint can be either on the direction/axis only ( magconon = 1) or on the full vector ( magconon = 2). The penalty function has an amplitude magcon_lambda that should be neither too big (bad or impossible convergence) nor too small (no effect). The penalty function is documented in [Ma2015] as being a Lagrange approach, which is a misnomer for the algorithm that they describe. It has the drawback of being unable to deliver the exact sought value for the magnetization. So, the true Lagrange approach has to be preferred, except for testing purposes. This is provided by the algorithm governed by the input variable constraint_kind, which is actually also much more flexible than the implementation corresponding to magconon .

Final subtlety: when magconon = 1, if nspden==2 (collinear case), then the direction of magnetization is constraint (positive or negative along z), while if nspden==4, then the axis of magnetization is constraint (the actual direction is not imposed, both directions are equivalent). This might be confusing.

mixalch

Mnemonics: MIXing coefficients for ALCHemical potentials
Characteristics: EVOLVING
Mentioned in topic(s): topic_AtomTypes
Variable type: real
Dimensions: (%npspalch,ntypalch)
Default value: None
Added in version: before_v9

Test list (click to open). Rarely used, [8/1245] in all abinit tests, [0/159] in abinit tutorials

Used for the generation of alchemical pseudoatoms, that is, when ntypalch is non-zero.

This array gives, for each type of alchemical pseudo-atom (there are ntypalch such pseudoatoms), the mixing coefficients of the basic %npspalch pseudopotentials for alchemical use. For each type of alchemical pseudoatom, the sum of the mixing coefficients must equal 1.

The actual use of the mixing coefficients is defined by the input variable algalch. Note that the masses of the atoms, amu are also mixed according to the value of mixalch , by default.

Example 1. Suppose that we want to describe Ba(0.25) Sr(0.75) Ti O_3. The input variables related to the construction of the alchemical Ba(0.25) Sr(0.75) potential will be:

  npsp   4                 ! 4 pseudopotentials should be read.
  znucl  8 40 56 38        ! The nuclear charges. Note that the two
                           ! atoms whose pseudopotentials are to be mixed
                           ! are mentioned at the end of the series.
  ntypat  3                ! There will be three types of atoms.
  ntypalch   1             ! One pseudoatom will be alchemical.
                           ! Hence, there will be ntyppure=2 pure pseudo-atoms,
                           ! with znucl 8 (O) and 40 (Ti), corresponding to
                           ! the two first pseudopotentials. Out of the
                           ! four pseudopotentials, npspalch=2 are left
                           ! for alchemical purposes, with znucl 56 (Ba)
                           ! and 38 (Sr).
  mixalch    0.25  0.75    ! For that unique pseudo-atom to be
                           ! generated, here are the mixing coefficients,
                           ! to be used to combine the Ba and Sr pseudopotentials.

Example 2. More complicated, and illustrate some minor drawback of the design of input variables. Suppose that one wants to generate Al(0.25)Ga(0.75) As(0.10)Sb(0.90). The input variables will be:

  npsp  4                  ! 4 pseudopotentials should be read
  znucl  13 31 33 51       ! The atomic numbers. All pseudopotentials
                           ! will be used for some alchemical purpose
  ntypat  2                ! There will be two types of atoms.
  ntypalch   2             ! None of the atoms will be "pure".
                           ! Hence, there will be npspalch=4 pseudopotentials
                           !  to be used for alchemical purposes.
  mixalch    0.25  0.75 0.0  0.0   ! This array is a (4,2) array, arranged in the
             0.0   0.0  0.1  0.9   ! usual Fortran order.

Minor drawback: one should not forget to fill mixalch with the needed zero’s, in this later case.

In most cases, the use of mixalch will be as a static (non-evolving) variable. However, the possibility to have different values of mixalch for different images has been coded. A population of cells with different atomic characteristics can thus be considered, and can be made to evolve, e.g. with a genetic algorithm (not coded in v7.0.0 though). There is one restriction to this possibility: the value of %ziontypat for the atoms that are mixed should be identical.

natsph

Mnemonics: Number of ATomic SPHeres for the atom-projected density-of-states
Mentioned in topic(s): topic_printing, topic_ElecBandStructure, topic_ElecDOS, topic_AtomCentered
Variable type: integer
Dimensions: scalar
Default value: natom
Only relevant if: prtdos == 3 or 4 or pawfatbnd in [1,2]
Added in version: before_v9

Test list (click to open). Rarely used, [8/1245] in all abinit tests, [2/159] in abinit tutorials

natsph gives the number of atoms around which the sphere for atom-projected density-of-states will be built, in the prtdos = 3 or 4 case. The indices of these atoms are given by iatsph. The radius of these spheres is given by ratsph. If pawfatbnd = 1 or 2, it gives the number of atoms around which atom-projected band structure will be built (the indices of these atoms are given by iatsph).

natsph_extra

Mnemonics: Number of ATomic SPHeres for the l-projected density-of-states in EXTRA set
Mentioned in topic(s): topic_printing, topic_AtomCentered
Variable type: integer
Dimensions: scalar
Default value: 0
Only relevant if: prtdos == 3 or 4 or pawfatbnd in [1,2]
Added in version: before_v9

Test list (click to open). Rarely used, [1/1245] in all abinit tests, [0/159] in abinit tutorials

natsph_extra gives the number of extra spheres for which the angular- momentum-projected density-of-states will be built, in the prtdos = 3 or 4 case. The radius of these spheres is given by ratsph_extra. This simulates the STS signal for an STM tip atom placed at the sphere position, according to the chemical nature of the tip (s- p- d- wave etc…). If pawfatbnd = 1 or 2, it gives the number of spheres in which l-projected band structure will be built. The position of the spheres is given by the xredsph_extra variable.

nbdbuf

Mnemonics: Number of BanDs for the BUFfer
Mentioned in topic(s): topic_SCFControl, topic_BandOcc
Variable type: integer
Dimensions: scalar
Default value: 2*nspinor if optdriver == 0 and iscf<0, 2*nspinor if optdriver == 1 and 3<=occopt and occopt<= 8, 0 otherwise.

Added in version: before_v9

Test list (click to open). Moderately used, [241/1245] in all abinit tests, [22/159] in abinit tutorials

nbdbuf gives the number of bands, the highest in energy, that, among the nband bands, are to be considered as part of a buffer. A negative value (between -1 and -100) is interpreted as percentage of nband (added in v9). The value -101 is special, as described below.

Important

The default value is usually too small, especially when performing GS NSCF calculations. In this case, it is strongly recommended to specify nbdbuf in the input and increase nband accordingly. For small systems (e.g. Silicon), nbdbuf = 4 is OK so using nband 12 and nbdbuf = 4 will give a band structure with the first 8 bands converged within tolwfr. For more complex systems and/or GS NSCF calculations with many empty states, one usually needs to increase nbdbuf , let’s say 10% of nband. This can be easily achieved by using a negative value e.g.: nbdbuf -10 means 10% of nband.

This concept is useful in three situations: in non-self-consistent calculations, for the determination of the convergence tolerance; for response functions of metals, to avoid instabilities, and also when finite electric fields or non-linear responses (with electric field perturbations) are considered. For the two first, the need of a buffer is a natural requirement of the problem, so that the default value is changed to 2 automatically, as explained in the following. The third case is only for implementation convenience.

In non-self-consistent GS calculations (iscf<0), the highest levels might be difficult to converge, if they are degenerate with another level, that does not belong to the set of bands treated. Then, it might take extremely long to reach tolwfr, although the other bands are already extremely well-converged, and the energy of the highest bands (whose residual are not yet good enough), is also rather well converged.

In response to this problem, for non-zero nbdbuf , the largest residual (residm), to be later compared with tolwfr, will be computed only in the set of non-buffer bands (this modification applies for non-self-consistent as well as self-consistent calculation, for GS as well as RF calculations). For a GS calculation, with iscf<0, supposing nbdbuf is not initialized in the input file, then ABINIT will overcome the default nbdbuf value, and automatically set nbdbuf to 2.

In metallic RF calculations, in the conjugate gradient optimisation of first-order wavefunctions, there is an instability situation when the q wavevector of the perturbation brings the eigenenergy of the highest treated band at some k-point higher than the lowest untreated eigenenergy at some k+q point. If one accepts a buffer of frozen states, this instability can be made to disappear. Frozen states receive automatically a residual value of -0.1 For a RF calculation, with 3 <= occopt <= 7, supposing nbdbuf is not initialized in the input file, then ABINIT will overcome the default nbdbuf value, and automatically set nbdbuf to 2. This value might be too low in some cases.

Also, the number of active bands, in all cases, is imposed to be at least 1, irrespective of the value of nbdbuf .

With nbdbuf = -101, the bands in the buffer are automatically defined through their occupancies. The convergence criteria is normally resid < tolwfr, which means that the squared band residual should be lower than tolwfr. With nbdbuf = -101, the convergence criteria becomes : resid * occ < tolwfr, where occ is the band occupancy. In that case, bands with null occupation numbers are completely ignored and bands with partial band occupancies are converged according to a modified criteria, equal to tolwfr/occ. This functionality is still experimental and has not been tested on many systems yet.

At last, we note that the convergence criteria for the diagonalization algorithm (see tolwfr_diago) is also affected by nbdbuf .

nblock_lobpcg

Mnemonics: Number of BLOCKs in the LOBPCG algorithm
Mentioned in topic(s): topic_SCFAlgorithms
Variable type: integer
Dimensions: scalar
Default value: 1
Only relevant if: wfoptalg = 4, 14, or 114
Added in version: v9.11.6

Test list (click to open). Moderately used, [19/1245] in all abinit tests, [0/159] in abinit tutorials

This variable controls the number of blocks in the LOBPCG algorithm. It has to be a divisor of nband. Contrary to the simple conjugate gradient, which is a band-by-band algorithm, LOBPCG can work on blocks of wavefunctions. This is partly why LOBPCG is more robust and efficient, especially for systems with many atoms. The size of a block is nband / nblock_lobpcg. Blocks are treated sequentially, starting from the block of bands with the lowest eigenvalues up to the block of bands with the highest eigenvalues.

With the default value, all bands are included in a single block (nblock_lobpcg=1), but it is very likely not the most efficient solution. To increase the number of blocks (which decreases the block size) can be interesting as:

  • it decreases the time spend in every LOBPCG call (a part of the work to be done on each block is proportional to (blocksize)^3).
  • it decreases the memory footprint, as the size of many work arrays is proportional to the block size.

However, to increase the number of blocks has some drawbacks:

  • it decreases the algorithm robustness, so difficult systems may not converge. To use one block is the most robust choice.
  • it decreases the convergence rate, so either more steps (see nstep) are needed to converge, or more “lines” are needed (see nline).
  • when used in a parallel computation, it decreases the scalability, so less cores can be used efficiently.

A first try could be nblock_lobpcg=4. If possible one can slightly adapt nband in order to be a multiple of nblock_lobpcg.

When use with paral_kgb=1, the bands of a block are distributed among npband MPI processes. So npband has to be a divisor of nband / nblock_lobpcg and bandpp is internally set to nband / (nblock_lobpcg * npband). nblock_lobpcg and bandpp cannot be used simultaneously, one should prefer nblock_lobpcg.

ndivk

Mnemonics: Number of DIVisions of K lines
Characteristics: INPUT_ONLY
Mentioned in topic(s): topic_k-points, topic_ElecBandStructure
Variable type: integer
Dimensions: (abs(kptopt))
Default value: None
Comment: Will be generated automatically from ndivsm if the latter is defined, which is much more convenient.
Only relevant if: kptopt < 0
The use of this variable forbids the use of: ndivsm
Added in version: before_v9

Test list (click to open). Rarely used, [11/1245] in all abinit tests, [4/159] in abinit tutorials

Gives the number of divisions of each of the segments of the band structure, whose path is determined by kptopt and kptbounds. In this case, the absolute value of kptopt is the number of such segments.

For example, suppose that the number of segment is just one (kptopt = -1), a value ndivk = 4 will lead to the computation of points with relative coordinates 0.0, 0.25, 0.5, 0.75 and 1.0, along the segment in consideration.

Now, suppose that there are two segments (kptopt = -2), with ndivk (1)=4 and ndivk (2)=2, the computation of the eigenvalues will be done at 7 points, 5 belonging to the first segment, with relative coordinates 0.0, 0.25, 0.5, 0.75 and 1.0, the last one being also the starting point of the next segment, for which two other points must be computed, with relative coordinates 0.5 and 1.0.

It is easy to compute disconnected circuits (non-chained segments), by separating the circuits with the value ndivk = 1 for the intermediate segment connecting the end of one circuit with the beginning of the next one (in which case no intermediate point is computed along this segment).

Alternatively it is possible to generate automatically the array ndivk by just specifying the number of divisions for the smallest segment. See the related input variable ndivsm. This is much more convenient than using ndivk .

ndivsm

Mnemonics: Number of DIVisions for the SMallest segment
Characteristics: INPUT_ONLY
Mentioned in topic(s): topic_k-points, topic_ElecBandStructure
Variable type: integer
Dimensions: scalar
Default value: None
Added in version: before_v9

Test list (click to open). Rarely used, [11/1245] in all abinit tests, [5/159] in abinit tutorials

This variable defines the number of divisions used to sample the smallest segment of the circuit employed in a band structure calculations (see related input variables kptopt and kptbounds). If ndivsm is given in the input file, there is no need to specify the number of divisions to be used for the other segments. Indeed ndivk is automatically calculated inside the code in order to generate a path where the number of divisions in each segment is proportional to the length of the segment itself. This option is activated only when kptopt is negative. In this case, the absolute value of kptopt is the number of such segments.

ngfft

Mnemonics: Number of Grid points for Fast Fourier Transform
Mentioned in topic(s): topic_Planewaves
Variable type: integer
Dimensions: (3)
Default value: [0, 0, 0]
Comment: (automatic selection of optimal values)
Added in version: before_v9

Test list (click to open). Moderately used, [85/1245] in all abinit tests, [0/159] in abinit tutorials

Gives the size of fast Fourier transform (FFT) grid in three dimensions. Each number must be composed of the factors 2, 3, and 5 to be consistent with the radices available in our FFT.

If no ngfft is provided or if ngfft is set to 0 0 0, the code will automatically provide an optimal set of ngfft values, based on acell, rprim and ecut (see also boxcutmin for speed/accuracy concerns). This is the recommended procedure, of course. The total number of FFT points is the product: ngfft (1) x ngfft (2) x ngfft (3)=%nfft.

When ngfft is made smaller than recommended values (e.g. by setting boxcutmin to a value smaller than 2.0 or by setting ngfft manually), the code runs faster and the equations in effect are approximated by a low pass Fourier filter. The code reports to standard output (unit 06) a parameter “boxcut” which is the smallest ratio of the FFT box side to the \GG vector basis sphere diameter. When boxcut is less than 2 the Fourier filter approximation is being used. When boxcut gets less than about 1.5 the approximation may be too severe for realistic results and should be tested against larger values of ngfft . When boxcut is larger than 2, ngfft could be reduced without loss of accuracy. In this case, the small variations that are observed are solely due to the xc quadrature, that may be handled with intxc = 1 to even reduce this effect.

Internally, ngfft is an array of size 18. The present components are stored in ngfft (1:3), while

  • ngfft (4:6) contains slightly different (larger) values, modified for efficiency of the FFT
  • ngfft (7) is fftalg
  • ngfft (8) is fftcache
  • ngfft (9) is set to 0 if the parallelization of the FFT is not activated, while it is set to 1 if it is activated.
  • ngfft (10) is the number of processors of the FFT group
  • ngfft (11) is the index of the processor in the group of processors
  • ngfft (12) is n2proc, the number of x-z planes, in reciprocal space, treated by the processor
  • ngfft (13) is n3proc, the number of x-y planes, in real space, treated by the processor
  • ngfft (14) is mpi_comm_fft, the handle on the MPI communicator in charge of the FFT parallelisation
  • ngfft (15:18) are not yet used

The number of points stored by this processor in real space is n1*n2*n3proc, while in reciprocal space, it is n1*n2proc*n3.

ngqpt

Mnemonics: Number of Grid points for Q PoinTs generation
Characteristics: INPUT_ONLY
Mentioned in topic(s): topic_q-points
Variable type: integer
Dimensions: (3)
Default value: [0, 0, 0]
Only relevant if: nqpt == 1 and kptopt >= 0
The use of this variable forbids the use of: qptrlatt
Added in version: before_v9

Test list (click to open). Moderately used, [35/1245] in all abinit tests, [16/159] in abinit tutorials

WARNING : Only used if nqpt = 1. If nqpt=0 (which is the default value of nqpt), no reading of ngqpt is done, and the default value of ngqpt is kept.

Similar to ngkpt, but for the q-wavevector. At variance with ngkpt, note that only one q point is selected per dataset (see iqpt). Its three positive components give the number of q points of Monkhorst-Pack grids (defined with respect to primitive axis in reciprocal space) in each of the three dimensions. The use of nshiftq and shiftq, allows one to generate shifted grids, or Monkhorst-Pack grids defined with respect to conventional unit cells.

For more information on Monkhorst-Pack grids, see ngkpt.

nline

Mnemonics: Number of LINE minimizations
Mentioned in topic(s): topic_SCFControl
Variable type: integer
Dimensions: scalar
Default value: 6 if wfoptalg == 1 or 11 , 4 otherwise.

Comment: 4 for conjugate-gradient-based algorithm, 6 for spectrum-filtering-based algorithms
Added in version: before_v9

Test list (click to open). Very frequently used, [1242/1245] in all abinit tests, [159/159] in abinit tutorials

For conjugate-gradient based algorithms (conjugate gradient or LOBPCG):

nline gives the maximum number of line minimizations allowed in preconditioned conjugate gradient minimization for each band. The default, 4, is fine. Special cases, with degeneracies or near-degeneracies of levels at the Fermi energy may require a larger value of nline (5 or 6 ?). Line minimizations will be stopped anyway when improvement gets small (governed by tolrde). Note that nline = 0 can be used to diagonalize the Hamiltonian matrix in the subspace spanned by the input wavefunctions.

For algorithms using spectrum filtering (f.i. Chebyshev filtering, wfoptalg=1 or 111):

nline gives the maximum degree of the Chebyshev polynomial used as filtering function. The default is 6 to ensure a good quality of the filtering.

With the input variable nnsclo, nline governs the convergence of the wavefunctions for fixed potential.

npsp

Mnemonics: Number of PSeudoPotentials to be read
Characteristics: NO_MULTI
Mentioned in topic(s): topic_AtomTypes, topic_PseudosPAW
Variable type: integer
Dimensions: scalar
Default value: ntypat
Added in version: before_v9

Test list (click to open). Moderately used, [27/1245] in all abinit tests, [3/159] in abinit tutorials

Usually, the number of pseudopotentials to be read, npsp , is equal to the number of type of atoms, ntypat. However, in the case an alchemical mixing of pseudopotential is used, npsp will be bigger than ntypat.

Alchemical pseudopotentials will be present when ntypalch is non-zero. See ntypalch to understand how to use alchemical potentials in ABINIT. The input variables (ntypalch, algalch, mixalch) are active, and generate alchemical potentials from the available pseudopotentials. Also, the inner variables (%ntyppure, %npspalch) become active. See these input variables, especially mixalch, to understand how to use alchemical potentials in ABINIT.

npspalch

Mnemonics: Number of PSeudoPotentials that are “ALCHemical”
Characteristics: INTERNAL_ONLY
Mentioned in topic(s): topic_AtomTypes
Variable type: integer
Dimensions: scalar
Default value: npsp-%ntyppure
Only relevant if: ntypalch>0
Added in version: before_v9

Gives the number of pseudopotentials that are used for alchemical mixing (when ntypalch is non-zero):

npspalch = npsp-%ntyppure

When alchemical mixing of potentials is used (that is, when ntypalch>0), then npspalch must be greater than 0.

nqfd

Mnemonics: Number of Quasi Fermi-Dirac excited carriers
Characteristics: INPUT_ONLY
Mentioned in topic(s): topic_BandOcc, topic_DeltaSCF
Variable type: real
Dimensions: scalar
Default value: 0.0
Added in version: v9

Test list (click to open). Rarely used, [1/1245] in all abinit tests, [0/159] in abinit tutorials

Only used if [[occopt] = 9.

Controls the numbers of electrons per cell constrained in conduction bands with index strictly greater than ivalence, and the number of holes per cell constrained in valence bands with index between 1 and ivalence. Internal variables ne_qFD (number of electrons) and nh_qFD (number of holes) are presently initialized to nqfd , which is NOT INTERNAL.

nqpt

Mnemonics: Number of Q - POINTs
Mentioned in topic(s): topic_q-points
Variable type: integer
Dimensions: scalar
Default value: 0
Added in version: before_v9

Test list (click to open). Moderately used, [213/1245] in all abinit tests, [19/159] in abinit tutorials

Determines whether one q point must be read (See the variable %qptn). Can be either 0 or 1.

If 1 and used in ground-state calculation, a global shift of all the k-points is applied, to give calculation at k+q. In this case, the output wavefunction will be appended by _WFQ instead of _WFK Also, if 1 and a RF calculation is done, defines the wavevector of the perturbation.

For further information about the naming of files in ABINIT, consult the abinit help file.

nshiftq

Mnemonics: Number of SHIFTs for Q point grids
Characteristics: INPUT_ONLY
Mentioned in topic(s): topic_q-points
Variable type: integer
Dimensions: scalar
Default value: 1
Added in version: before_v9

Test list (click to open). Rarely used, [7/1245] in all abinit tests, [3/159] in abinit tutorials

WARNING : Only used if nqpt = 1. If nqpt=0 (which is the default value of nqpt), no reading of nshiftq is done, and the default value of nshiftq is kept.

This parameter gives the number of shifted grids to be used concurrently to generate the full grid of q points. It can be used with primitive grids defined either from ngqpt or qptrlatt. The maximum allowed value of nshiftq is 8. The values of the shifts are given by shiftq.

nspden

Mnemonics: Number of SPin-DENsity components
Mentioned in topic(s): topic_spinpolarisation
Variable type: integer
Dimensions: scalar
Default value: nsppol
Added in version: before_v9

Test list (click to open). Moderately used, [118/1245] in all abinit tests, [7/159] in abinit tutorials

If nspden = 1, no spin-magnetization the density matrix is diagonal, with same values spin-up and spin-down (compatible with nsppol = 1 only, for both nspinor = 1 or 2)

If nspden = 2, scalar magnetization (the axis is arbitrarily fixed in the z direction) the density matrix is diagonal, with different values for spin-up and spin-down (compatible with nspinor = 1, either with nsppol = 2 -general collinear magnetization- or nsppol = 1 -antiferromagnetism)

If nspden = 4, vector magnetization: the density matrix is full, with allowed x, y and z magnetization (useful only with nspinor = 2 and nsppol = 1, either because there is spin-orbit without time-reversal symmetry - and thus spontaneous magnetization, or with spin-orbit, if one allows for spontaneous non-collinear magnetism). Available for response functions [Ricci2019]. Not yet available for mGGA. Also note that, with nspden = 4, time-reversal symmetry is not taken into account (at present; this has to be checked) and thus kptopt has to be different from 1 or 2.

The default ( nspden = nsppol) does not suit the case of vector magnetization. Note that the choice of nspden has an influence on the treatment of symmetries. See symafm.

nspinor

Mnemonics: Number of SPINORial components of the wavefunctions
Mentioned in topic(s): topic_spinpolarisation
Variable type: integer
Dimensions: scalar
Default value: 2 if pawspnorb == 1, 1 otherwise.

Added in version: before_v9

Test list (click to open). Moderately used, [112/1245] in all abinit tests, [8/159] in abinit tutorials

If nspinor = 1, usual case: scalar wavefunction (compatible with (nsppol = 1, nspden = 1) as well as (nsppol = 2, nspden = 2) )

If nspinor = 2, the wavefunction is a spinor (compatible with nsppol = 1, with nspden = 1 or 4, but not with nsppol = 2)

When nspinor is 2, the values of istwfk are automatically set to 1. Also, the number of bands, for each k-point, should be even.

ntypalch

Mnemonics: Number of TYPe of atoms that are “ALCHemical”
Mentioned in topic(s): topic_AtomTypes
Variable type: integer
Dimensions: scalar
Default value: 0
Added in version: before_v9

Test list (click to open). Rarely used, [8/1245] in all abinit tests, [0/159] in abinit tutorials

Used for the generation of alchemical pseudopotentials: when ntypalch is non-zero, alchemical mixing will be used.

Among the ntypat types of atoms, the last ntypalch will be “alchemical” pseudoatoms, while only the first %ntyppure will be uniquely associated with a pseudopotential (the %ntyppure first of these, actually). The ntypalch types of alchemical pseudoatoms are to be made from the remaining %npspalch pseudopotentials.

In this case, the input variables algalch, mixalch are active, and generate alchemical potentials from the available pseudopotentials. See these input variables, especially mixalch, to understand how to use alchemical potentials in ABINIT.

ntyppure

Mnemonics: Number of TYPe of atoms that are “PURE”
Characteristics: INTERNAL_ONLY
Mentioned in topic(s): topic_AtomTypes
Variable type: integer
Dimensions: scalar
Default value: ntypat-ntypalch
Added in version: before_v9

Gives the number of type of atoms that are “pure” when alchemical mixing is used (ntypalch /= 0):

ntyppure = ntypat - ntypalch

nucdipmom

Mnemonics: NUClear DIPole MOMents
Mentioned in topic(s): topic_NMR, topic_MagField
Variable type: real
Dimensions: (3,natom)
Default value: 0.0
Only relevant if: %usepaw = 1; pawcpxocc = 2; optforces = 0; optstress = 0; kptopt = 0, 4, or 3
Added in version: before_v9

Test list (click to open). Rarely used, [9/1245] in all abinit tests, [1/159] in abinit tutorials

Places an array of nuclear magnetic dipole moments on the atomic positions, useful for computing the magnetization in the presence of nuclear dipoles and thus the chemical shielding by the converse method (see orbmag, [Thonhauser2009] and [Zwanziger2023]). The presence of these dipoles breaks time reversal symmetry and lowers the overall spatial symmetry. The dipole moment values are entered in atomic units, as vectors in the Cartesian (not crystallographic) coordinate frame. For reference, note that one Bohr magneton has value 1/2 in atomic units, while one nuclear Bohr magneton has value 2.7321\times 10^{-4} in atomic units.

nwfshist

Mnemonics: Number of WaveFunctionS HISTory
Mentioned in topic(s): topic_Wavelets
Variable type: integer
Dimensions: scalar
Default value: 0
Added in version: before_v9

Test list (click to open). Moderately used, [16/1245] in all abinit tests, [9/159] in abinit tutorials

In the wavelet basis set, the ground state is found by direct minimisation. The algorithm used can be either the steepest descent or the DIIS (Direct Inversion of Iteration Space). When nwfshist = 0, the steepest descent is used ( i.e. there is no history storage of the previous iterations).

If nwfshist is strictly positive, a DIIS is used. A typical value is 6. Using a DIIS increases the memory required by the program since N previous wavefunctions are stored during the electronic minimisation.

occ

Mnemonics: OCCupation numbers
Characteristics: EVOLVING
Mentioned in topic(s): topic_BandOcc
Variable type: real
Dimensions: (nband,nsppol)
Commentdims: in case occopt=2, dimensions are (%mband,nkpt,nsppol)
Default value: 0
*Added in version: before_v9

Test list (click to open). Very frequently used, [712/1245] in all abinit tests, [79/159] in abinit tutorials

Gives occupation numbers for all bands in the problem. Needed if occopt == 0 or occopt == 2. Ignored otherwise (automatically computed). Also ignored when iscf = -2. Typical band occupancy is either 2.0 or 0.0, but will usually be 1.0 or 0.0 for nsppol=2, or nspinor=2, or half-occupied band, or other choices in special circumstances.

If occopt is not 2, then the occupancies must be the same for each k point. If nsppol=1, the total number of arrays which must be provided is nband, in order of increasing energy. If nsppol=2, the total number of arrays which must be provided is nband*nsppol, first spin up, in order of increasing electronic eigenenergy, then spin down, in order of increasing electronic eigenenergy.

If occopt = 2, then the band occupancies must be provided explicitly for each band, EACH k POINT, and EACH SPIN-POLARIZATION, in an array which runs over all bands, k points, and spin-polarizations. The order of entries in the array would correspond to all bands at the first k point (spin up), then all bands at the second k point (spin up), etc, then all k-points spin down. The total number of array elements which must be provided is ( nband(1)+nband(2)+…+ nband(nkpt) ) * nsppol.

The occupation numbers evolve only for metallic occupations, that is, occopt ≥ 3.

When there are several images, occ might depend on the image number, see the description in nimage.

optdriver

Mnemonics: OPTions for the DRIVER
Mentioned in topic(s): topic_nonlinear, topic_GWls, topic_ElPhonInt, topic_GW, topic_BSE, topic_DFPT, topic_Susceptibility, topic_SelfEnergy
Variable type: integer
Dimensions: scalar
Default value: 0
Added in version: before_v9

Test list (click to open). Moderately used, [190/1245] in all abinit tests, [35/159] in abinit tutorials

For each dataset, choose the task to be done, at the level of the “driver” routine.

The choice is among:

  • 0 → ground-state calculation (GS), routine gstate
  • 1 → response-function calculation (RF), routine respfn
  • 2 → susceptibility calculation (SUS), routine suscep
  • 3 → susceptibility and dielectric matrix calculation (SCR), routine screening
  • 4 → self-energy calculation (SIG), routine sigma.
  • 5 → non-linear response functions (NONLINEAR), using the 2n+1 theorem, routine nonlinear.
  • 6 → GW real space imaginary time driver (GWR), using the [Liu2016] algorithm, routine gwr_driver, see gwr_task.
  • 7 → electron-phonon coupling (EPH), see also eph_task input variable.
  • 8 → Post-processing of WFK file, routine wfk_analyze. See also wfk_task input variable.
  • 10 → longwave response functions (LONGWAVE), routine longwave. See also lw_flexo, lw_qdrpl or lw_natopt input variables.
  • 66 → GW using Lanczos-Sternheimer, see input variables whose name start with gwls_*.
  • 99 → Bethe-Salpeter calculation (BSE), routine bethe_salpeter

If one of rfphon, rfddk, rfelfd, or rfstrs is non-zero, while optdriver is not defined in the input file, ABINIT will set optdriver to 1 automatically. These input variables (rfphon, rfddk, rfelfd, and rfstrs) must be zero if optdriver is not set to 1.

optstress

Mnemonics: OPTion for the computation of STRESS
Mentioned in topic(s): topic_ForcesStresses
Variable type: integer
Dimensions: scalar
Default value: 1
Added in version: before_v9

Test list (click to open). Moderately used, [80/1245] in all abinit tests, [17/159] in abinit tutorials

If set to 1, the computation of stresses is done, in the SCF case (under the conditions iscf > 0, prtstm == 0, positron == 0, and either nstep >0, or %usepaw == 0 or irdwfk == 1). Otherwise, to save CPU time, if no optimization of the cell is required, one can skip the computation of stresses. The CPU time saving might be interesting for some PAW calculations.

posdoppler

Mnemonics: POSitron computation of DOPPLER broadening
Mentioned in topic(s): topic_positron
Variable type: integer
Dimensions: scalar
Default value: 0
Added in version: before_v9

Test list (click to open). Rarely used, [3/1245] in all abinit tests, [2/159] in abinit tutorials

Relevant only when positron/=0. This input parameter activates the calculation of the Doppler broadening of the electron-positron annihilation radiation. An output file containing the momentum distributions of annihilating electron-positron pairs is created. Such a computation needs a core wave-function file (per atom type) to be provided. This core WF file should be named ‘psp_file_name.corewf’ (where pspfile_name is the name of the pseudo-potential (or PAW) file) or ‘corewf.abinit**ityp**’ (where ityp is the index of the atom type). Core WF files can be obtained with the atompaw tool by the use of prtcorewf keyword.

positron

Mnemonics: POSITRON calculation
Mentioned in topic(s): topic_positron
Variable type: integer
Dimensions: scalar
Default value: 0
Added in version: before_v9

Test list (click to open). Rarely used, [11/1245] in all abinit tests, [7/159] in abinit tutorials

This input parameter can be positive or negative. Negative values for positron are only relevant for PAW calculations. Electron-positron correlation functional is defined by ixcpositron. Other relevant input parameter: posocc (occupation number for the positron).

Positive values for positron : For positron = 1 or 2, will perform the calculation of positron lifetime (and annihilation rate).

  • positron = 1:\n Starting from a previous electronic GS density (with positron = 0), a positronic ground-state calculation is performed, considering that the electrons are not perturbed by the presence of the positron. This is almost correct for a positron in a perfect bulk material. But this approximation fails when defects exist in the material (for instance: the positron might be trapped by a vacancy). The electronic density will be automatically read from a _DEN file (with or without irdden keyword). At the end of the SCF cycle, the positron lifetime and annihilation rate are printed out.

Additional information for the use of pseudopotentials:

PAW datasets: nothing to do; simply use usual electronic PAW datasets
Norm-conserving pseudopotentials: One has to use specific pseudopotentials for the positron calculation. They must be of the FHI type (pspcod=6), and must contain at their end, the all-electrons core density generated with FHI98PP. They must have lmax=lloc=0 (check that this works for the electronic GS !! No ghost, etc...). Otherwise, their are similar to an usual FHI pseudopotential.
  • positron = 2:\n Starting from a previous positronic GS density (with positron = 1 ), an electronic ground-state calculation is performed, keeping the positronic density constant. The positronic density will be automatically read from a _DEN file (with or without getden/irdden keyword). At the end of the SCF cycle, the positron lifetime and annihilation rate are printed out.

Additional information for the use of pseudopotentials:

PAW datasets: nothing to do; simply use usual electronic PAW datasets
Norm-conserving pseudopotentials: One has to use specific pseudopotentials for the electron calculation. They must be of the FHI type (pspcod=6), and must contain at their end, the all-electrons core density generated with FHI98PP.
  • Typical use:\n The calculation is done in several steps: The first one is a normal GS calculation for the electrons, with positron = 0. The only specific thing to do is to set prtden = 1 (this is the default for ABINIT v6.x+). This will create the associated _DEN file which will be used as input file for the positronic GS calculation. The second step is the GS calculation of the positron and subsequently its lifetime, with positron =1. One has to define also ixcpositron. Then, it is possible to perform an additional step, computing the GS electronic density in presence of the positron, with positron = 2 and so on… This procedure can be automated (for PAW only) by the use of a negative value for positron . At the end, a converged value of the positron lifetime (decomposed in several contributions) is printed. See also posdoppler keyword for the calculation of Doppler broadening.

Negative values for positron :\n For positron <0, will perform an automatic calculation of electrons and positron densities in the two-component DFT context; then will compute positron lifetime (and annihilation rate).

  • positron = -1:\n Starting from scratch, will first perform a usual electronic ground-state calculation until convergence (controlled by the use of one of the tolerance keywords). Then will perform a positronic ground state calculation in presence of the electrons and ions; then an electronic ground state calculation in presence of the positron and the ions and so on until the total energy is converged. The convergence of the total energy of the ions+electrons+positron system is controlled by the use of the postoldfe, postoldff and posnstep input keywords. With positron = -1, at the beginning of each new electronic/positronic step, the wave functions are unknown.

  • positron = -10:\n Same as positron = -1 except that the electronic/positronic wave functions are stored in memory. Consequently, the total number of iterations to reach the convergence (\DeltaEtotal<postoldfe or \DeltaForces<postoldff) is smaller. But, this can increase the total amount of memory needed by the code.

  • positron = -2:\n Same as positron = -1 except that the two-component DFT cycle is forced to stop at the end of an electronic step.

  • positron = -20:\n Same as positron = -10 except that the two-component DFT cycle is forced to stop at the end of an electronic step.

Advice for use: There are two typical cases which have to be differently treated:

  • A positron in a perfect bulk system:\n In that case, the positron is delocalized in the whole crystal. Its density is almost zero. Thus, the “zero density positron limit” has to be used. ixcpositron has to be chosen accordingly. In order to have the zero density positron limit it is advised to follow these points:

  • 1- Put a small positronic charge (by setting a posocc to a small value) OR use a big supercell.

  • 2- Use only k=\Gamma wave vector for the positronic calculation.
  • 3- Use the manual procedure in 2 steps: first positron = 0 and then positron = 1; avoid the positron = 2 step and the automatic procedure ( positron <0).

In principle, the positron lifetime should converge with the value of posocc or the size of the supercell.

  • A positron trapped in a default (vacancy):\n In that case, the positron is localized in the default. Its density can be localized in the simulation cell (provided that the cell is sufficiently large) and influences the electronic density. So, it is advised to use the automatic procedure ( positron <0) or the manual procedure with several positron = 0,1,2,1,… steps. K-points can be used as in usual electronic calculations. Also note that it is possible to use forces and stresses to perform structural minimization.

References: [Arponen1979a], [Boronski1986], [Sterne1991], [Puska1995], [Barbiellini1995]

posnstep

Mnemonics: POSitron calculation: max. Number of STEPs for the two-component DFT
Mentioned in topic(s): topic_positron
Variable type: integer
Dimensions: scalar
Default value: 50
Added in version: before_v9

Test list (click to open). Rarely used, [6/1245] in all abinit tests, [4/159] in abinit tutorials

Relevant only when positron<0. Sets the maximum number of electronic/positronic iterations that, when reached, will cause the two-component DFT SCF cycle to stop. The code will first compute the electronic ground-state, then the positronic ground state in the electronic density, then the electronic ground state in the positronic density until \DeltaEtotal<postoldfe or \DeltaForces<postoldff or the number of electronic/positronic steps is posnstep .

posocc

Mnemonics: POSitron calculation: OCCupation number for the positron
Mentioned in topic(s): topic_positron
Variable type: real
Dimensions: scalar
Default value: 1
Added in version: before_v9

Test list (click to open). Rarely used, [9/1245] in all abinit tests, [7/159] in abinit tutorials

Relevant only when positron/=0. Sets the occupation number for the positron. Has to be <=1. Changing posocc is only useful for bulk calculation when one wants to perform lifetime computations using a small simulation cell (can avoid the use of a supercell). It simulates the dispersion of the positron in the whole crystal.

postoldfe

Mnemonics: POSitron calculation: TOLerance on the DiFference of total Energy
Characteristics: ENERGY
Mentioned in topic(s): topic_positron
Variable type: real
Dimensions: scalar
Default value: 1e-06 if postoldff = 0, 0.0 otherwise.

Added in version: before_v9

Test list (click to open). Rarely used, [4/1245] in all abinit tests, [2/159] in abinit tutorials

Relevant only when positron<0. Sets a tolerance for absolute difference of total energy (of ions+electrons+positron system) that, when reached, will cause the SCF cycle to stop before the number of steps is nstep or the number of electronic/positronic steps is posnstep.

Can be specified in Ha (the default), Ry, eV or Kelvin, since postoldfe has the ENERGY characteristics. One and only one of postoldfe or postoldff can be set.

postoldff

Mnemonics: POSitron calculation: TOLerance on the DiFference of Forces
Mentioned in topic(s): topic_positron
Variable type: real
Dimensions: scalar
Default value: 0
Added in version: before_v9

Test list (click to open). Rarely used, [1/1245] in all abinit tests, [0/159] in abinit tutorials

Relevant only when positron < 0. Sets a tolerance for absolute difference of maximum force (in hartree/Bohr) acting on ions (due to ions+electrons+positron system) that, when reached, will cause the SCF cycle to stop before the number of SCF steps is nstep or the number of electronic/positronic steps is posnstep. One and only one of postoldfe or postoldff can be set.

prt_lorbmag

Mnemonics: PRinT L ORBital MAGnetic moment inside PAW spheres
Mentioned in topic(s): topic_printing, topic_AtomCentered
Variable type: integer
Dimensions: scalar
Default value: 0
Only relevant if: nspden == 4 and %usepaw == 1 and usepawu != 0
Added in version: v9

Test list (click to open). Rarely used, [1/1245] in all abinit tests, [0/159] in abinit tutorials

If set to 1, prints in the output the orbital magnetic moment integrated inside the PAW spheres (Bohr magneton). The orbital magnetic moment is resolved orbital by orbital (p, d and f, the s orbital moment being always zero) on each atom. Works only if PAW and DFT+U is used and if the spin-orbit coupling is on (with nspden == 4).

prtdensph

Mnemonics: PRinT integral of DENsity inside atomic SPHeres
Mentioned in topic(s): topic_printing
Variable type: integer
Dimensions: scalar
Default value: 1 otherwise.

Added in version: before_v9

Test list (click to open). Moderately used, [16/1245] in all abinit tests, [0/159] in abinit tutorials

When this flag is activated, values of integral(s) of total density inside sphere(s) around each atom are printed in output file (for each spin component). Spheres around atoms are defined by a radius given by ratsph keyword. Note: integral of density inside a sphere around an atom can be used to determine a rough approximation of the local magnetic moment; this is particularly useful for antiferromagnetic systems. The algorithm to compute this integral is particularly primitive: the points on the FFT grids, belonging to the interior of the sphere are determined, and the value of the functions on these points are summed, taking into account a fixed volume attributed to each point. In particular, the integral as a function of the radius will be a constant, except when a new point enters the sphere, in which case a sudden jump occurs. However, since the purpose of this output is to get a rough idea of the repartition of the density, this is not a real problem. If you are interested in a more accurate estimation of the density within a sphere, you should use the cut3d postprocessor (cut3d help file).

prtebands

Mnemonics: PRinT Electron BANDS
Mentioned in topic(s): topic_printing
Variable type: integer
Dimensions: scalar
Default value: 0 if nimage > 1, 1 otherwise.

Added in version: before_v9

Test list (click to open). Rarely used, [7/1245] in all abinit tests, [1/159] in abinit tutorials

This option activates the output of the electron eigenvalues. Possible values:

  • 0- Disable the output of the band energies.
  • 1- Write eigenvalues in xmgrace format. A file with extension EBANDS.agr is produced at the end of the run. Use xmgrace file_EBANDS.agr to visualize the band energies
  • 2- Write eigenvalues in gnuplot format. The code produces a EBANDS.dat file with the eigenvalues and a file_EBANDS.gnuplot script. Use gnuplot file_EBANDS.gnuplot to visualize the band energies.

qpt

Mnemonics: Q PoinT
Characteristics: INPUT_ONLY
Mentioned in topic(s): topic_q-points
Variable type: real
Dimensions: (3)
Default value: [0, 0, 0]
Added in version: before_v9

Test list (click to open). Moderately used, [235/1245] in all abinit tests, [31/159] in abinit tutorials

WARNING : Only used if nqpt = 1. If nqpt=0 (which is the default value of nqpt), no reading of qpt is done, and the default value of qpt , namely the null vector, is kept.

Combined with qptnrm, define the q vector %qptn(1:3) in the case qptopt = 0.

This input variable is not internal (%qptn(1:3) is used instead), but is used to echo the value of %qptn(1:3), with renormalisation factor one.

qptnrm

Mnemonics: Q PoinTs NoRMalization
Characteristics: INPUT_ONLY
Mentioned in topic(s): topic_q-points
Variable type: real
Dimensions: scalar
Default value: 1.0
Added in version: before_v9

Test list (click to open). Rarely used, [2/1245] in all abinit tests, [0/159] in abinit tutorials

Only used if nqpt = 1 and qptopt = 0

Provides re-normalization of qpt. Must be positive, non-zero. The actual q vector (renormalized) is %qptn(1:3)= qpt(1:3)/ qptnrm .

qptopt

Mnemonics: QPoinTs OPTion
Characteristics: INPUT_ONLY
Mentioned in topic(s): topic_q-points
Variable type: integer
Dimensions: scalar
Default value: 0
Added in version: before_v9

Test list (click to open). Moderately used, [14/1245] in all abinit tests, [4/159] in abinit tutorials

WARNING : Only used if nqpt = 1. If nqpt=0 (which is the default value of nqpt), no reading of qptopt is done, and the default value of qptopt is kept.

Controls the set up to generate the Q point %qptn(1:3) to be used for the specific dataset, either as a shift of k-point grid in ground-state calculations, or as a stand-alone phonon wavevector.

There are two basic techniques to generate the Q point: either by specifying it directly, possibly with a renormalisation factor ( qptopt = 0), or extracting it from a grid a Q points ( qptopt = 1 to 4), using the index iqpt. At variance with the similar generation of k points, only ONE q point can be used per dataset.

With qptopt = 1 to 4, rely on ngqpt or qptrlatt, as well as on nshiftq and shiftq to set up a q point grid, from which the q point with number iqpt will be selected. The values qptopt = 1 to 4 differ by the treatment of symmetries. Note that the symmetries are recomputed starting from the values of %rprimd, xred and spinat. So, the explicit value of symrel are not used. This is to allow doing calculations with nsym = 1, sometimes needed for T-dependent electronic structure, still decreasing the number of q points in the case qptopt = 1 or qptopt = 3.

  • 0 → read directly qpt, and its (possible) renormalisation factor qptnrm.

  • 1 → Take fully into account the symmetry to generate the grid of q points in the Irreducible Brillouin Zone only. (This is the usual mode for RF calculations)

  • 2 → Take into account only the time-reversal symmetry: q points will be generated in half the Brillouin zone.

  • 3 → Do not take into account any symmetry: q points will be generated in the full Brillouin zone.

  • 4 → Take into account all the symmetries EXCEPT the time-reversal symmetry to generate the k points in the Irreducible Brillouin Zone.

In the case of a grid of q points, the auxiliary variables kptrlen, ngkpt and prtkpt might help you to select the optimal grid, similarly to the case of the K point grid.

qptrlatt

Mnemonics: Q - PoinTs grid: Real space LATTice
Characteristics: INPUT_ONLY
Mentioned in topic(s): topic_q-points
Variable type: integer
Dimensions: (3,3)
Default value: 0
*The use of this variable forbids the use of: ngqpt
Added in version: before_v9

Test list (click to open). Rarely used, [1/1245] in all abinit tests, [0/159] in abinit tutorials

WARNING : Only used if nqpt = 1. If nqpt=0 (which is the default value of nqpt), no reading of qptrlatt is done, and the default value of qptrlatt is kept.

This input variable is used only when qptopt is positive. It partially defines the q point grid. The other piece of information is contained in shiftq. qptrlatt cannot be used together with ngqpt.

The values qptrlatt (1:3,1), qptrlatt (1:3,2), qptrlatt (1:3,3) are the coordinates of three vectors in real space, expressed in the %rprimd coordinate system (reduced coordinates). They define a super-lattice in real space. The k point lattice is the reciprocal of this super-lattice, possibly shifted (see shiftq).

If neither ngqpt nor qptrlatt are defined, ABINIT will automatically generate a set of k point grids, and select the best combination of qptrlatt and shiftq that allows one to reach a sufficient value of kptrlen. See this latter variable for a complete description of this procedure.

ratsm

Mnemonics: Radii of the ATomic spheres SMearing
Mentioned in topic(s): topic_printing, topic_MagMom, topic_ConstrainedDFT
Variable type: real
Dimensions: scalar
Default value: 0.05 if any(constraint_kind > 1), 0.0 otherwise.

Added in version: before_v9

Test list (click to open). Rarely used, [12/1245] in all abinit tests, [0/159] in abinit tutorials

Smearing width for the atomic spheres whose radius is determined by ratsph. For each spherical zone around each atom, the integrating function goes from 1.0 to 0.0 in an interval from ratsph- ratsm to ratsph. The function is the same as the one used to smear the kinetic energy, see ecutsm.

ratsph

Mnemonics: Radii of the ATomic SPHere(s)
Mentioned in topic(s): topic_printing, topic_MagMom, topic_ElecBandStructure, topic_ElecDOS, topic_ConstrainedDFT, topic_AtomCentered
Variable type: real
Dimensions: (ntypat)
Default value: AUTO_FROM_PSP if %usepaw == 1, 2.0 otherwise.

Added in version: before_v9

Test list (click to open). Moderately used, [20/1245] in all abinit tests, [3/159] in abinit tutorials

Relevant only when prtdensph = 1, or magconon/=0, or any(constraint_kind(:)/=0) (that is, constrained DFT), or prtdos = 3. In most cases (see later for prtdos = 3), provides the radius of the spheres around each atom in which the total charge density or magnetization will be integrated. The integral within the sphere is obtained by a sum over real space FFT points inside the sphere, multiplied by a function that is one inside the sphere, except in a small boundary zone determined by ratsm, where this function goes smoothly from 1 to 0. In case of PAW, ratsph radius has to be greater or equal to PAW radius of considered atom type (which is read from the PAW dataset file; see rc_sph or r_paw). In case of constrained DFT, note that the sphere for different atoms are not allowed to overlap.

When prtdos = 3 or 4 :

Provides the radius of the spheres around the natsph atoms of indices iatsph, in which the local DOS and its angular-momentum projections will be analysed.

The choice of this radius is quite arbitrary. In a plane-wave basis set, there is no natural definition of an atomic sphere. However, it might be wise to use the following well-defined and physically motivated procedure: from the Bader analysis, one can define the radius of the sphere that contains the same charge as the Bader volume. This “Equivalent Bader charge atomic radius” might then be used to perform the present analysis. See the aim help file for more explanations. Another physically motivated choice would be to rely on another charge partitioning, like the Hirshfeld one (see the cut3d utility cut3d help file). The advantage of using charge partitioning schemes comes from the fact that the sum of atomic DOS, for all angular momenta and atoms, integrated on the energy range of the occupied states, gives back the total charge. If this is not an issue, one could rely on the half of the nearest- neighbour distances, or any scheme that allows one to define an atomic radius. Note that the choice of this radius is however critical for the balance between the s, p and d components. Indeed, the integrated charge within a given radius, behave as a different power of the radius, for the different channels s, p, d. At the limit of very small radii, the s component dominates the charge contained in the sphere.

ratsph_extra

Mnemonics: Radii of the ATomic SPHere(s) in the EXTRA set
Characteristics: LENGTH
Mentioned in topic(s): topic_printing, topic_AtomCentered
Variable type: real
Dimensions: scalar
Default value: 2.0 Bohr
Added in version: before_v9

Test list (click to open). Rarely used, [1/1245] in all abinit tests, [0/159] in abinit tutorials

Radius for extra spheres the DOS is projected into. See natsph_extra and xredsph_extra for the number and positions of the spheres.

rcut

Mnemonics: Radius of the CUT-off for coulomb interaction
Mentioned in topic(s): topic_Coulomb, topic_GWls, topic_Susceptibility, topic_SelfEnergy
Variable type: real
Dimensions: scalar
Default value: 0.0
Added in version: before_v9

Test list (click to open). Moderately used, [19/1245] in all abinit tests, [0/159] in abinit tutorials

Truncation of the Coulomb interaction in real space. The meaning of rcut is governed by the cutoff shape options icutcoul, gw_icutcoul and/or fock_icutcoul. See complementary information in vcutgeo.

In the method of Ismail-Beigi [Ismail-Beigi2006] for one-dimensional systems, the cutoff region is given by the Wigner-Seitz cell centered on the axis of the cylinder. The cutoff region is thus automatically defined by the unit cell and there is no need to specify the value of rcut . For two-dimensional systems, Ismail-Beigi [Ismail-Beigi2006] also fixes the cutoff region, at half the replication length perpendicular to the (truly) periodic plane.

Thus, when the Beigi methods in 1D or 2D are expected, rcut must be 0.0. Using another value of rcut will prevent the Beigi method to be used. See complementary information in vcutgeo.

On the other hand, when the Rozzi methods in 1D or 2D are expected, which is the case when one component of vcutgeo is negative, rcut mut be defined.

If rcut is negative, the cutoff is automatically calculated so to enclose the same volume inside the cutoff as the volume of the primitive cell.

rmm_diis

Mnemonics: Activate the RMM-DIIS eigensolver for GS calculations.
Mentioned in topic(s): topic_TuningSpeedMem, topic_SCFAlgorithms
Variable type: integer
Dimensions: scalar
Default value: 0
Added in version: 9.3.0

Test list (click to open). Rarely used, [10/1245] in all abinit tests, [0/159] in abinit tutorials

This variable activates the Residual Minimization Method, Direct Inversion in the Iterative Subspace (RMM-DIIS) eigensolver to accelerate GS computations, structural relaxations and molecular-dynamics simulations. The algorithm is inspired to [Kresse1996] although the ABINIT implementation is not completely equivalent to the original formulation. RMM-DIIS can be used both with NC and PAW pseudos and is fully compatible with the paral_kgb distribution. Note, however, that PAW seems to be more sensitive to some internal tricks used to accelerate the computation so you should not expect to see the same speedup as in the NC case. This variable has no effect when optdriver > 0.

It is worth noting that RMM-DIIS is usually employed in conjunction with another eigenvalue solver that is used to perform the initial SCF iterations. RMM-DIIS, indeed, is not guaranteed to converge to the ground state as the algorithm will find the eigenvector/eigenvalue pair closest to the input trial state. The reliability of RMM-DIIS thus strongly depends on the initialisation of the SCF cycle and on the quality of the input wavefunctions that are supposed to be reasonably close to the final solution.

Both the CG and the LOBPCG solver can be used in conjunction with RMM-DIIS although it is strongly suggested to use LOBPCG with paral_kgb = 1 to take advantage of its better efficiency and improved parallel scalability. To activate RMM-DIIS with e.g. LOBPCG, it is sufficient to use:

paral_kgb 1
rmm_diis  1

in the input file and then select the value of np_spkpt, npband, npfft, npspinor according to the system.

Tip

Using use_gemm_nonlop = 1 with bandpp > 1 can lead to a significant speedup at the price of increased memory requirements.

In the case of standard SCF calculations, Abinit activates the RMM-DIIS solver after 3 + rmm_diis SCF iterations. When performing structural relaxations, RMM-DIIS is activated after rmm_diis SCF iterations once the first GS calculation is completed. This means that using rmm_diis = 1 for a structural relaxation leads to:

    - 4 SCF iterations with the CG/LOBPCG eigensolver followed by RMM-DIIS when are performing the **first GS calculation**.
    - 1 SCF iterations with CG/LOBPCG followed by RMM-DIIS for all the subsequent relaxation steps.

A negative value rmm_diis (e.g. -3) can be used to bypass the initial CG/LOBPCG iterations but this option should be used with extreme care and it is not recommended in general.

RMM-DIIS usually requires less wall-time per iteration when compared to other approaches since there is no explicit orthogonalization while optimizing the trial states. Only a single full-band Cholesky orthogonalization is performed per SCF iteration before recomputing the new density. As a consequence, one RMM-DIIS iteration is usually faster (sometimes even by a factor two) than one CG/LOBPCG iteration, especially in systems with relatively large %mpw. However, the additional steps of the algorithm (subspace rotation and Cholesky orthogonalization) present poor MPI-scalability hence this part will start to dominate the wall-time in systems with large nband.

The algorithm can also be used for NSCF band structure calculations although one should not expect RMM-DIIS to provide high-energy states of the same quality as the one obtained with other eigenvalue solvers. Although RMM-DIIS can be used for computing band structures and electron DOS with iscf = -2, we do not recommend using this solver to produce WFK files with many empty states as required by many-body calculations.

From the above discussion, it should be clear that RMM-DIIS is less stable than the other eigenvalue solvers and you should be aware (and accept) that RMM-DIIS calculations may fail. In the best case scenario, one clearly sees the problem as the SCF cycle does not convergence and/or the code aborts with a non-zero exit status returned by one of the LAPACK routines. In the worst case scenario, RMM-DIIS may seamlessly converge to the wrong solution. This is especially true if the first LOBPCG/CG iterations fail to provide a reasonably-good initial starting point.

In problematic cases, you may want to increase the value of rmm_diis so that more SCF iterations are done with LOBPCG/CG before activating RMM-DIIS. RMM-DIIS is indeed very sensitive to density mixing and increasing rmm_diis is a possible solution if you don’t want to play with the variables defining the mixing algorithm.

As a general rule, we strongly suggest to include in the calculation more nband bands that what is strictly needed to accommodate all the valence electrons (let’s say > 10% of the occupied bands). Increasing nband, indeed, increases the number of vectors used for the Rayleigh-Ritz subspace rotation and this step is crucial for finding the most accurate variational approximation to the eigenvectors before starting the DIIS optimization.

For a given precision, RMM-DIIS usually requires more iterations than the other eigensolvers. For performance reasons, one should avoid using tight tolerances. Something of the order of tolvrs = 1e-8 or toldfe = 1e-10 to stop the SCF cycle should be fine. Avoid using (tolwfr) (criterion on the residuals) as converge criterion for SCF cycles Use tolwfr only if you are using RMM-DIIS for NSCF band structure calculations (as this is the only converge criterion available for NSCF calculations).

Last but not least, note that the default implementation is quite aggressive at the level of memory allocations. A less memory-intensive version of the algorithm can be activated via rmm_diis_savemem = 1.

rmm_diis_savemem

Mnemonics: Save memory in the RMM-DIIS eigensolver.
Mentioned in topic(s): topic_TuningSpeedMem
Variable type: integer
Dimensions: scalar
Default value: 0
Added in version: 9.3.0

Test list (click to open). Rarely used, [2/1245] in all abinit tests, [0/159] in abinit tutorials

This variable allows one to save memory in the RMM-DIIS eigensolver when rmm_diis /= 0. By default, the RMM-DIIS routine allocates two extra arrays to reduce the number of applications of the Hamiltonian. The size of these arrays depends on the number of plane-waves treated by each processor and nband. The amount of memory scales with npband and npfft yet this extra memory is not negligible and the code may go out of memory for large systems. In this case, one can use rmm_diis_savemem = 1 to activate a version of RMM-DIIS that avoids these extra allocations.

scphon_supercell

Mnemonics: Self Consistent PHONon SUPERCELL
Mentioned in topic(s): topic_DFPT
Variable type: integer
Dimensions: (3)
Default value: [1, 1, 1]
Added in version: before_v9

Test list (click to open). Rarely used, [0/1245] in all abinit tests, [0/159] in abinit tutorials

Give extent, in number of primitive unit cells, of the supercell being used for a self-consistent phonon calculation. Presumes the phonon frequencies and eigenvectors have been calculated in the original primitive unit cell, on a grid of q-points which corresponds to the supercell in the present calculation. Experimental.

scphon_temp

Mnemonics: Self Consistent PHONon TEMPerature
Characteristics: ENERGY
Mentioned in topic(s): topic_DFPT
Variable type: real
Dimensions: scalar
Default value: 0.0
Added in version: before_v9

Test list (click to open). Rarely used, [0/1245] in all abinit tests, [0/159] in abinit tutorials

Temperature which is imposed on phonon distribution, in the self-consistent scheme of [Souvatzis2008]. Determines the extent of the finite displacements used, and consequent anharmonic effects. Experimental.

shiftq

Mnemonics: SHIFT for Q points
Characteristics: INPUT_ONLY
Mentioned in topic(s): topic_q-points
Variable type: real
Dimensions: (3,nshiftq)
Default value: None if nshiftq>1, [0.5, 0.5, 0.5] otherwise.

Added in version: before_v9

Test list (click to open). Rarely used, [9/1245] in all abinit tests, [3/159] in abinit tutorials

WARNING : Only used if nqpt = 1. If nqpt=0 (which is the default value of nqpt), no reading of shiftq is done, and the default value of shiftq is kept.

It is used only when qptopt >= 0, and must be defined if nshiftq is larger than 1. shiftq (1:3,1:nshiftq) defines nshiftq shifts of the homogeneous grid of q points based on ngqpt or qptrlatt.

See shiftk for more information on the definition, use, and suitable values for these shifts.

slabwsrad

Mnemonics: jellium SLAB Wigner-Seitz RADius
Characteristics: LENGTH
Mentioned in topic(s): topic_Artificial
Variable type: real
Dimensions: scalar
Default value: 0.0
Added in version: before_v9

Test list (click to open). Rarely used, [4/1245] in all abinit tests, [0/159] in abinit tutorials

Fix the bulk-mean positive charge density n_{bulk} of a jellium slab (if the latter is employed, e.g. jellslab/=0). Often called r_s (see for example [Lang1970]), slabwsrad is the radius of a sphere which has the same volume as the average volume per particle in a homogeneous electron gas with density n_{bulk}, so:

\begin{equation} \frac{1}{n_{bulk}} = \frac{4 \pi}{3} **slabwsrad** ^3 \nonumber \end{equation}

For example, the bulk aluminum fcc lattice constant is a=4.0495 Angstroms WebElements, each cubic centered cell includes 4 Al atoms and each atom has 3 valence electrons, so the average volume per electron is a^3/12=37.34 Bohr^3 which has to be equal to \frac{4 \pi}{3} r_s^3. Consequently Al has approximately r_s=2.07 Bohr, while for example magnesium has r_s=2.65 Bohr, sodium 3.99 Bohr. By default, given in Bohr atomic units (1 Bohr=0.5291772108 Angstroms).

slabzbeg

Mnemonics: jellium SLAB BEGinning edge along the z-direction
Mentioned in topic(s): topic_Artificial
Variable type: real
Dimensions: scalar
Default value: 0.0
Added in version: before_v9

Test list (click to open). Rarely used, [4/1245] in all abinit tests, [0/159] in abinit tutorials

Define the edges of the jellium slab (if used, so if jellslab/=0) along z, namely the slab starts at a point along z which is expressed in Bohr by slabzbeg and it ends at a point expressed in Bohr by slabzend. The z-direction is parallel to the third crystal primitive lattice vector which has to be orthogonal to the other ones, so the length of the cell along z is %rprimd(3,3). In addition slabzbeg and slabzend have to be such that:

  0 ≤  **slabzbeg**   < [[slabzend]] ≤ [[rprimd]](3,3)

Together with slabwsrad they define the jellium positive charge density distribution n_{+}(x,y,z) in this way:

\begin{eqnarray} n_{+}(x,y,z) &=& n_{bulk} \quad \text{if} \quad **slabzbeg** \leq z \leq [[slabzend]] \nonumber\\ &=& 0 \quad \text{otherwise} \nonumber \end{eqnarray}

so the positive charge density is invariant along the xy plane as well as the electrostatic potential generated by it.

slabzend

Mnemonics: jellium SLAB ENDing edge along the z-direction
Mentioned in topic(s): topic_Artificial
Variable type: real
Dimensions: scalar
Default value: 0.0
Added in version: before_v9

Test list (click to open). Rarely used, [4/1245] in all abinit tests, [0/159] in abinit tutorials

Define the edges of the jellium slab (if used, so if jellslab/=0) along z, namely the slab starts at a point along z which is expressed in Bohr by slabzbeg and it ends at a point expressed in Bohr by slabzend . The z-direction is parallel to the third crystal primitive lattice vector which has to be orthogonal to the other ones, so the length of the cell along z is %rprimd(3,3). In addition slabzbeg and slabzend have to be such that:

  0 ≤ [[slabzbeg]] <  **slabzend**   ≤ [[rprimd]](3,3)

Together with slabwsrad they define the jellium positive charge density distribution n_{+}(x,y,z) in this way:

\begin{eqnarray} n_{+}(x,y,z) &=& n_{bulk} \quad \text{if} \quad [[slabzbeg]] \leq z \leq **slabzend** \nonumber \\ &=& 0 \quad \text{otherwise} \nonumber \end{eqnarray}

so the positive charge density is invariant along the xy plane as well as the electrostatic potential generated by it.

slk_rankpp

Mnemonics: ScaLapacK matrix RANK Per Process
Mentioned in topic(s): topic_parallelism
Variable type: integer
Dimensions: scalar
Default value: [1000]
Added in version: before_v9

Test list (click to open). Rarely used, [1/1245] in all abinit tests, [0/159] in abinit tutorials

This variable controls how the number of processes to be used in Scalapack diagonalization algorithm: np_slk will be calculated according to this value. This value is the matrix rank that each process will hold for the diagonalization. For a 1000x1000 matrix with default value, scalapack won’t be used (Lapack will be used). For a 2000x2000 matrix with default value, scalapack will be used with 2000/1000=2 MPI processes. For a 2000x2000 matrix with a slk_rank=500, scalapack will be used with 2000/500=4 MPI processes. In case of hybrid MPI+OpenMP, the number of thread is also taken into account.

WARNING None of the available scalapack library are thread-safe (2018). Therefore using both scalapack and OpenMP is highly unpredictable. Furthermore, using multithreaded linear algebra library (MKL ACML…) is more efficient than pure MPI scalapack.

Usually it is better to define this variable and let the code do the rest.

so_psp

Mnemonics: Spin-Orbit treatment for each PSeudoPotential
Mentioned in topic(s): topic_spinpolarisation
Variable type: integer
Dimensions: (npsp)
Default value: npsp * 1
Only relevant if: nspinor == 2 and %usepaw == 0
Added in version: before_v9

Test list (click to open). Moderately used, [50/1245] in all abinit tests, [0/159] in abinit tutorials

For each type of atom (each pseudopotential), specify the treatment of spin-orbit interaction (if nspinor == 2 and Norm-conserving pseudopotentials i.e. %usepaw == 0) For PAW calculations with SOC, please refer to pawspnorb.

  • If 0: no spin-orbit interaction, even if nspinor = 2
  • If 1: treat spin-orbit as specified in the pseudopotential file.
  • If 2: treat spin-orbit in the HGH form (usual form, although not allowed for all pseudopotentials)
  • If 3: treat spin-orbit in the HFN form (Hemstreet-Fong-Nelson) (actually, not implemented).

For typical usage, the default value is OK. If the spin-orbit needs to be turned off for one atom, 0 might be relevant. Note however, that the code will stop if nspinor == 2 is used and one of the pseudopotential does not contain the information about the spin-orbit interaction (this is the case for some old pseudopotentials). Indeed, for spinorial calculations, turning off the spin-orbit interaction is unphysical, and also does not save CPU time. It should only be done for test purposes

Note that if nspinor == 1, the spin-orbit cannot be treated anyhow, so the value of so_psp is irrelevant.

Prior to v5.4, the input variable so_typat was used, in place of so_psp . Because the values 0 and 1 have been switched between so_psp and so_typat, it was dangerous to continue to allow the use of so_typat.

spinat

Mnemonics: SPIN for AToms
Mentioned in topic(s): topic_spinpolarisation, topic_crystal, topic_MagMom, topic_ConstrainedDFT
Variable type: real
Dimensions: [3, natrd ] if natrd<natom, [3, natom ] otherwise.

Default value: 0.0
Added in version: before_v9

Test list (click to open). Moderately used, [155/1245] in all abinit tests, [18/159] in abinit tutorials

Gives the initial electronic spin-magnetization for each atom, in unit of \hbar/2, as well as, in case of fixed magnetization calculations (see constraint_kind and magconon), the target value of the magnetization.

Note that if nspden = 2, the z-component must be given for each atom, in triplets (0 0 z-component). For example, the electron of an hydrogen atom can be spin up (0 0 1.0) or spin down (0 0 -1.0).

This value is only used to create the first exchange and correlation potential. It is not checked against the initial occupation numbers occ for each spin channel. It is meant to give an easy way to break the spin symmetry, and to allow to find stable local spin fluctuations, for example: antiferromagnetism, or the spontaneous spatial spin separation of elongated H_2 molecule.

  • If the atom manipulator is used, spinat will be related to the preprocessed set of atoms, generated by the atom manipulator. The user must thus foresee the effect of this atom manipulator (see objarf).

  • If the atom manipulator is not used, and the symmetries are not specified by the user (nsym = 0), spinat will be used, if present, to determine the anti-ferromagnetic characteristics of the symmetry operations, see symafm. In case of collinear antiferromagnetism (nsppol = 1, nspinor = 1, nspden = 2), these symmetries are used to symmetrize the density. In case of non-collinear magnetism (nsppol = 1, nspinor = 2, nspden = 4), they are also used to symmetrize the density. In the latter case, this strongly constrains the magnetization (imposing its direction). If the user want to let all degrees of freedom of the magnetization evolve, it is then recommended to put nsym = 1.

  • If the symmetries are specified, and the irreducible set of atoms is specified, the anti-ferromagnetic characteristics of the symmetry operations symafm will be used to generate spinat for all the non-irreducible atoms.

  • In the case of PAW+U calculations using the dmatpawu initial occupation matrix, and if nspden = 4, spinat is also used to determine the direction of the integrated magnetization matrix.

stmbias

Mnemonics: Scanning Tunneling Microscopy BIAS voltage
Characteristics: ENERGY
Mentioned in topic(s): topic_STM
Variable type: real
Dimensions: scalar
Default value: 0.0
Added in version: before_v9

Test list (click to open). Rarely used, [1/1245] in all abinit tests, [0/159] in abinit tutorials

Gives, in Hartree, the bias of the STM tip, with respect to the sample, in order to generate the STM density map. Used with positive iscf, occopt = 7 (metallic, gaussian), nstep = 1, and positive prtstm, this value is used to generate a charge density map from electrons close to the Fermi energy, in a (positive or negative) energy range. Positive stmbias will lead to the inclusion of occupied (valence) states only, while negative stmbias will lead to the inclusion of unoccupied (conduction) states only. Can be specified in Ha (the default), Ry, eV or Kelvin, since stmbias has the ENERGY characteristics (0.001 Ha = 27.2113845 meV = 315.773 Kelvin). With occopt = 7, one has also to specify an independent broadening tsmear.

supercell_latt

Mnemonics: SUPERCELL LATTice
Mentioned in topic(s): topic_UnitCell
Variable type: integer
Dimensions: (3)
Default value: [1, 1, 1]
Added in version: before v9

Test list (click to open). Rarely used, [1/1245] in all abinit tests, [0/159] in abinit tutorials

Factor that multiplies the three primitive vectors to generate a supercell. The starting nuclei types typat and coordinates xred and xcart are simply replicated in the different images of the original primitive cell. If present, spinat and chrgat are also replicated without change. Note that supercell_latt is not echoed. It is immediately used to change natom, typat, and all input variables that depend on natom and typat.

This input variable cannot be used jointly with non-default values of natrd and nobj. Also, nsym is set to 1. Also note that vel, if defined, must have the dimensions of the number of atoms in the supercell, not the initial natom, because it is not replicated. supercell_latt is typically used to initialize molecular dynamics runs.

symafm

Mnemonics: SYMmetries, Anti-FerroMagnetic characteristics
Mentioned in topic(s): topic_spinpolarisation
Variable type: integer
Dimensions: (nsym)
Default value: nsym * 1
Added in version: before_v9

Test list (click to open). Rarely used, [2/1245] in all abinit tests, [0/159] in abinit tutorials

In case the material is magnetic, nspden=2 or 4, additional symmetry operations might appear, that change the sign of the magnetization (spin-flip). They have been introduced by Shubnikov in 1951 [Bradley1972]. They can be used by ABINIT to decrease the CPU time, either by decreasing the number of k-points or by suppressing the explicit treatment of one spin channel, or by decreasing the number of perturbations in DFPT.

symafm should be set to +1 for all the usual symmetry operations, that do not change the sign of the magnetization, while it should be set to -1 for the magnetization-changing operations (spin-flip). If the symmetry operations are not specified by the user in the input file, that is, if nsym = 0, then ABINIT will use the values of spinat to determine the content of symafm .

The symmetries that can act on the magnetization can yield decreased CPU time (and usually also memory decrease) in the following cases:

Also in the case nsppol = 2, nspinor = 1, nspden = 2 they might simply yield better accuracy (or faster convergence), but there is no automatic gain of CPU time or memory, although it is not as clear cut as in the above cases.

IMPORTANT : The meaning of symafm is different in the nspden = 2 case (collinear magnetism), and in the nspden = 4 case (non-collinear magnetism, with explicit treatment of magnetization as a vector). Indeed in the first case, it is supposed that the magnetization vector is not affected by the real space symmetry operations (so-called black and white symmetry groups). By contrast, in the second case, the real space symmetry operations act on the magnetization vector. The rationale for such different treatment comes from the fact that the treatment of spin-orbit coupling is incompatible with collinear magnetism nspden=2, so there is no need to worry about it in this case. On the contrary, many calculations with nspden=4 will include spin-orbit coupling. The symmetry operations should thus act coherently on the spin-orbit coupling, which implies that the real space operations should act also on the magnetization vector in the nspden=4 case. So, with nspden=4, even with symafm =1, symmetry operations might change the magnetization vector, e.g. possibly reverse it from one atom to another atom. Still, when real space operations also act on the magnetization vector, nothing prevents to have ADDITIONAL “spin-flip” operations, which is indeed then the meaning of symafm =-1 in the nspden=4 case. Note that real-space operations act on the magnetization as an axial vector, not as a normal vector. For example, the inversion symmetry does not change the magnetization vector.

Let’s illustrate this with an example. Take an H_2 system, with the two H atoms quite distant from each other. The electron on the first H atom might be 1s spin up, and the electron on the second atom might be 1s spin down. With nspden=2, the inversion symmetry centered in the middle of the segment joining the two atoms will NOT act on the spin, so that the actual symmetry operation that leaves the system invariant is an inversion (symrel= -1 0 0 0 -1 0 0 0 -1) accompanied by a spin-flip with symafm =-1. By contrast, with nspden=4, the inversion symmetry centered in the middle of the segment joining the two atoms will reverse the spin direction as well, so that the proper symmetry operation is symrel= -1 0 0 0 -1 0 0 0 -1 but no additional spin-flip is needed to obtain a symmetry operation that leaves the system invariant, so that symafm =1.

Although this might seem confusing, ABINIT is able to recognise the correct symmetry operations from the available atomic coordinates, from spinat, and from nspden, so that the user should hardly be affected by such different conventions. However, the use of %ptgroupma and spgroupma to define the antiferromagnetic operations of symmetry should be done carefully.

Related variables: symrel, tnons, %ptgroupma, spgroupma.

timopt

Mnemonics: TIMing OPTion
Characteristics: NO_MULTI
Mentioned in topic(s): topic_Control
Variable type: integer
Dimensions: scalar
Default value: 1 if SEQUENTIAL, 0 otherwise.

Added in version: before_v9

Test list (click to open). Moderately used, [115/1245] in all abinit tests, [18/159] in abinit tutorials

This input variable allows one to modulate the use of the timing routines.

  • If 0 → as soon as possible, suppresses all calls to timing routines
  • If 1 → usual timing behaviour, with short analysis, appropriate for sequential execution
  • If 2 → close to timopt = 1, except that the analysis routine does not time the timer, appropriate for parallel execution.
  • If 3 → close to timopt = 1, except that the different parts of the lobpcg routine are timed in detail.
  • If 4 → close to timopt = 1, except that the different parts of the lobpcg routine are timed in detail. A different splitting of lobpcg than for timopt = -3 is provided.
  • If 10 → relevant only when the wavelet basis set is used (i.e. usewvl = 1). When activated, a file named wvl_timings.yaml, in YAML format, is created. It contains a time analysis of the BigDFT wavelet routines. See the tutorial on parallelism using wavelets
  • If -1 → a full analysis of timings is delivered
  • If -2 → a full analysis of timings is delivered, except timing the timer
  • If -3 → a full analysis of timings is delivered, including the detailed timing of the different parts of the lobpcg routine. (this takes time, and is discouraged for too small runs - the timing would take more time than the run !). The timer is timed.
  • If -4 → a full analysis of timings is delivered, including the detailed timing of the different parts of the lobpcg routine. A different splitting of lobpcg than for timopt = -3 is provided (this takes time, and is discouraged for too small runs - the timing would take more time than the run !). The timer is timed. The sum of the independent parts is closer to 100% than for timopt = -3.

tl_nprccg

Mnemonics: TaiL maximum Number of PReConditioner Conjugate Gradient iterations
Mentioned in topic(s): topic_Wavelets
Variable type: integer
Dimensions: scalar
Default value: 30
Added in version: before_v9

Test list (click to open). Rarely used, [1/1245] in all abinit tests, [0/159] in abinit tutorials

This variable is similar to wvl_nprccg but for the preconditioner iterations during the tail corrections (see tl_radius).

tl_radius

Mnemonics: TaiL expansion RADIUS
Characteristics: LENGTH
Mentioned in topic(s): topic_Wavelets
Variable type: real
Dimensions: scalar
Default value: 0.0
Added in version: before_v9

Test list (click to open). Rarely used, [1/1245] in all abinit tests, [0/159] in abinit tutorials

In the wavelet computation case, the linkage between the grid and the free boundary conditions can be smoothed using an exponential decay. This means a correction on the energy at the end on each wavefunction optimisation run. If this parameter is set to zero, no tail computation is done. On the contrary, put it to a positive value makes the tail correction available. The value correspond to a length in atomic units being the spacial expansion with the exponential decay around the grid.

tphysel

Mnemonics: Temperature (PHYSical) of the ELectrons
Characteristics: ENERGY
Mentioned in topic(s): topic_BandOcc
Variable type: real
Dimensions: scalar
Default value: 0.0
Added in version: before_v9

Test list (click to open). Rarely used, [6/1245] in all abinit tests, [0/159] in abinit tutorials

Gives, in Hartree, the physical temperature of the system, in case occopt = 4, 5, 6, or 7.

Can be specified in Ha (the default), Ry, eV or Kelvin, since tphysel has the ENERGY characteristics (0.001 Ha = 27.2113845 meV = 315.773 Kelvin). One has to specify an independent broadening tsmear. The combination of the two parameters tphysel and tsmear is described in [Verstraete2002]. Note that the signification of the entropy is modified with respect to the usual entropy. The choice has been made to use tsmear as a prefactor of the entropy, to define the entropy contribution to the free energy. Note that tphysel might be used as parameter for Free Energy exchange-correlation functionals (see ixc).

tsmear

Mnemonics: Temperature of SMEARing
Characteristics: ENERGY
Mentioned in topic(s): topic_BandOcc, topic_STM
Variable type: real
Dimensions: scalar
Default value: 0.01
Added in version: before_v9

Test list (click to open). Moderately used, [328/1245] in all abinit tests, [43/159] in abinit tutorials

Gives the broadening of occupation numbers occ, in the metallic cases (occopt = 3, 4, 5, 6 and 7). Can be specified in Ha (the default), eV, Ry, or Kelvin, since tsmear has the ENERGY characteristics (0.001 Ha = 27.2113845 meV = 315.773 Kelvin). Default is 0.01 Ha. This should be OK using gaussian like smearings (occopt = 4,5,6,7) for a free-electron metal like Al. For d-band metals, you may need to use less. Always check the convergence of the calculation with respect to this parameter, and simultaneously, with respect to the sampling of k-points (see nkpt) If occopt = 3, tsmear is the physical temperature, as the broadening is based on Fermi-Dirac statistics. However, if occopt = 4, 5, 6, or 7, the broadening is not based on Fermi-Dirac statistics, and tsmear is only a convergence parameter. It is still possible to define a physical temperature, thanks to the input variable tphysel (See also [Verstraete2002]).

useextfpmd

Mnemonics: USE EXTended FPMD model
Mentioned in topic(s): topic_ExtFPMD
Variable type: integer
Dimensions: scalar
Default value: 0
Added in version: 9.5.2

Test list (click to open). Rarely used, [1/1245] in all abinit tests, [0/159] in abinit tutorials

Enables the calculation of contributions to the energy, entropy, stresses, number of electrons and chemical potential using the extended First Principle Molecular Dynamics model for high temperature simulations.

For now, ExtFPMD is only available with occopt = 3, with tsmear defined as the electronic temperature. More occupation options will be supported in the future.

In case of electronic SCF cycle convergency problems, try to set a number of unoccupied bands in the buffer with extfpmd_nbdbuf input variable.

  • useextfpmd = 1 (Recommended), the energy shift will be evaluated by making an integration of the trial potential over the real space and the contributions will be computed using the density of states of the Fermi gas.

  • useextfpmd = 2, the energy shift will be evaluated by making the average between the eigenvalues and the Fermi gas energy over the last extfpmd_nbcut bands, and the contributions will be computed with integrals over the band number.

  • useextfpmd = 3, the energy shift will be evaluated by making the average between the eigenvalues and the kinetic energies over the last extfpmd_nbcut bands, and the contributions will be computed using the density of states of the Fermi gas.

  • useextfpmd = 4, the energy shift will be evaluated by making an integration of the trial potential over the real space and the contributions will be computed with integrals over the band number.

  • useextfpmd = 5, the energy shift will be evaluated by making an integration of the trial potential over the real space and the contributions will be computed with discrete integer sums over the band indices. extfpmd_nband sets the last band index, which acts like nband for a conventional calculation.

usekden

Mnemonics: USE Kinetic energy DENsity
Mentioned in topic(s): topic_xc
Variable type: integer
Dimensions: scalar
Default value: 0
Added in version: before_v9

Test list (click to open). Moderately used, [14/1245] in all abinit tests, [0/159] in abinit tutorials

If usekden = 1 the kinetic energy density will be computed during the self-consistent loop, in a way similar to the computation of the density. This is needed if a meta-GGA is to be used as XC functional. By default ( usekden = 0), the kinetic energy density is not computed during the self- consistent loop. usekden = 1 is not yet allowed with nspden=4 (non-collinear magnetism).

vacuum

Mnemonics: VACUUM identification
Characteristics: INPUT_ONLY
Mentioned in topic(s): topic_k-points
Variable type: integer
Dimensions: (3)
Default value: None
Added in version: before_v9

Test list (click to open). Moderately used, [23/1245] in all abinit tests, [4/159] in abinit tutorials

Establishes the presence (if vacuum = 1) or absence (if vacuum = 0) of a vacuum layer, along the three possible directions normal to the primitive axes.

This information might be used to generate k-point grids, if kptopt = 0 and neither ngkpt nor kptrlatt are defined (see explanations with the input variable prtkpt). It will allow to select a zero-, one-, two- or three-dimensional grid of k points. The coordinate of the k points along vacuum directions is automatically set to zero.

If vacuum is not defined, the input variable vacwidth will be used to determine automatically whether the distance between atoms is sufficient to have the presence or absence of vacuum.

vacwidth

Mnemonics: VACuum WIDTH
Characteristics: INPUT_ONLY, LENGTH
Mentioned in topic(s): topic_k-points
Variable type: real
Dimensions: scalar
Default value: 10.0
Added in version: before_v9

Test list (click to open). Rarely used, [1/1245] in all abinit tests, [0/159] in abinit tutorials

Give a minimum “projected” distance between atoms to be found in order to declare that there is some vacuum present for each of the three directions. By default, given in Bohr atomic units (1 Bohr=0.5291772108 Angstroms), although Angstrom can be specified, if preferred, since vacwidth has the LENGTH characteristics. The precise requirement is that a slab of width vacwidth , delimited by two planes of constant reduced coordinates in the investigated direction, must be empty of atoms.

vcutgeo

Mnemonics: V (potential) CUT-off GEOmetry
Mentioned in topic(s): topic_Coulomb, topic_GWls, topic_Susceptibility, topic_SelfEnergy
Variable type: real
Dimensions: (3)
Default value: 3 * 0.0
Only relevant if: icutcoul in [1,2]
Added in version: before_v9

Test list (click to open). Rarely used, [3/1245] in all abinit tests, [0/159] in abinit tutorials

vcutgeo is used in conjunction with icutcoul, fock_icutcoul and/or gw_icutcoul to specify the geometry used to truncate the Coulomb interaction, as well as the particular approach to be used. It has a meaning either for a periodic one-dimensional system, typically a nanowire, nanotube or polymer surrounded by vacuum separating the system from images in neighbouring cells (icutcoul = 1) or in the case of periodic two-dimensional system, typically a slab with vacuum separating it from images in neighbouring cells (icutcoul = 2).

When a non-zero component of this three-dimensional vector is non-zero, this indicate that the system is periodic along this dimension. Note that the components of this vector are real numbers, which is useful in the current implementation of the Rozzi methods [Rozzi2006]. Of course, just specifying 0 or 1 is allowed, but will be read as 0.0 or 1.0.

For each geometry, two different definitions of the cutoff region are available (see [Ismail-Beigi2006] and [Rozzi2006] for a complete description of the methods). The Beigi method is used by default. The Rozzi method is used if rcut is not at its default value (0.0), or if one component of vcutgeo is negative.

To define a cylinder along the z-axis use the following lines: 

icutcoul 1
vcutgeo  0 0 1

Please note that the method of Ismail-Beigi is implemented only in the case of an orthorhombic Bravais lattice. For hexagonal lattices, one has to use the method of Rozzi [Rozzi2006]. In this case, the interaction is truncated in a finite cylinder. Contrarily to the first approach, the user has to specify both the radius of the cylinder with rcut as well as the length of the cylinder along the periodic dimension, that should always be smaller than the extension of the Born von Karman box. The length of the cylinder is given in terms of a multiple of the primitive vector along the periodic direction. Another option provided by Rozzi [Rozzi2006] is the infinite length cylinder. In order to activate it in ABINIT, one needs to use a very large negative vcutgeo value on the third direction (i.e. vcutgeo(3) <= -999).

For example, in order to define a finite cylinder along z of radius 2.5 Bohr and length 3*R3, 

icutcoul 1
vcutgeo  0 0 -3.0 # note the minus sign
rcut     2.5

For two-dimensional systems (icutcoul = 2), vcutgeo is used to define the two periodic directions. Also in this case two different techniques are available. In the method of Ismail-Beigi, the (positive) non-zero components of vcutgeo define the periodic directions of the infinite surface. The interaction is truncated within a slab of width L where L is the projection of the primitive vector of the lattice along the direction perpendicular to the periodic plane. For example: 

icutcoul 2
vcutgeo  1 1 0
At present, the implementation of the Beigi technique for two-dimensional systems is restricted to the periodic directions being in the x-y plane.

In Rozzi’s method, it is also possible to define a finite range for the Coulomb interaction in the periodic directions by employing negative values. For example: 

icutcoul 2
vcutgeo -3 -2 0
Definition to be added

Note that not all k-point grids are allowed in these 1D and 2D cases: the k point vector component(s) along non-periodic direction(s) must vanish. So, if the 2D Ismail-Beigi technique is used, the z-component of the k points must vanish.

wfinit

Mnemonics: WaveFunctions INITialization
Mentioned in topic(s): topic_TuningSpeedMem, topic_SCFAlgorithms, topic_PseudosPAW
Variable type: integer
Dimensions: scalar
Default value: 0
Added in version: 9.9.0

Test list (click to open). Rarely used, [2/1245] in all abinit tests, [0/159] in abinit tutorials

This option specifies how to initialize the wavefunctions in the case of GS calculations. It requires pseudos with pseudized wavefunctions e.g. UPF2. Possible values are:

* 0: Start from random wavefunctions (default)
* 1: Use atomic orbitals + random numbers.
* 2: Use atomic orbitals without random numbers.

wfk_task

Mnemonics: WaveFunction at K TASK
Mentioned in topic(s): topic_ElecBandStructure
Variable type: string
Dimensions: scalar
Default value: 0
Only relevant if: optdriver == 8
Added in version: 9.0.0

Test list (click to open). Rarely used, [8/1245] in all abinit tests, [2/159] in abinit tutorials

This variable defines the quantity that should be computed starting from a previously generated WFK file. Possible values are:

  • “wfk_fullbz” → Read input WFK file and produce new WFK file with \kk-points in the full BZ. Wavefunctions with istwfk > 2 are automatically converted into the full G-sphere representation. This option can be used to interface Abinit with external tools (e.g. lobster) requiring \kk-points in the full BZ. Use iomode = 3 and prtkbff = 1 to produce a WFK file in netcdf format with Kleynmann-Bylander form factors.

  • “wfk_einterp” → Read energies from WFK file and interpolate the band structure with the modified SKW method [Pickett1988], using the parameters specified by einterp.

  • “wfk_ddk” → Compute velocity matrix elements for all bands and \kk-points found the input WFK file. The code generates three _EVK.nc netcdf files with the matrix element of the \frac{d}{d{\kk_i}} operator using the same list of \kk-points found in the input WFK file i.e. the same value of kptopt. These files can then be passed to optics via the ddkfile_1, ddkfile_2, ddkfile_3 variables without having to call the DFPT part that is much more expensive at the level of memory.

    Please note that, at present, the computation of non-linear optical properties in optic requires kptopt = 3 i.e. \kk-points in the full BZ whereas the computation of linear optical properties can take advantage of spatial and time-reversal symmetries. If you use wfk_ddk to generate input files for optics, please make sure that your input WFK file has the correct value of kptopt according to the physical properties you want to compute.

    In other words, don’t use a WFK with kptopt != 3 if you plan to compute non-linear optical properties. To work around the limitation of the non-linear part of optics, one can use “wfk_optics_fullbz” to generate WKF and EVK files in the full BZ starting from a WFK defined in the IBZ.

  • “wfk_optics_fullbz” → Similar to “wfk_ddk” but accepts a WFK with wavefunctions in the IBZ and generates a new WFK and three _EVK.nc files with \kk-points in the full BZ. This procedure is equivalent to performing a NSCF + DDK calculation with kptopt = 3 as documented in the tutorial optic tutorial for non-linear optical properties but it is much faster and, most importantly, less memory demanding.

  • “wfk_kpts_erange” → Read WFK file, use star-function and einterp parameters to interpolate electron energies onto fine k-mesh defined by sigma_ngkpt and sigma_shiftk. Find k-points inside (electron/hole) pockets according to the values specified by sigma_erange. Write KERANGE.nc file with all the tables required by the code to automate NSCF band structure calculations inside the pocket(s) and electron lifetime computation in the EPH code when eph_task = -4.

  • “wannier” → Read WFK file and run Wannierization. It has the similar effect of prtwant = 2, which uses the ABINIT- Wannier90 interface. The difference is that with wfk_task “wannier”, the \kk-points in the full BZ is not necessary. Instead, the wavefunctions with the \kk-points not in the IBZ will be reconstructed by symmetry. This functionality does not yet work with PAW when the wavefunction is not already in full BZ.

    ABINIT will produce the input files required by Wannier90 and it will run Wannier90 to produce the Maximally-locallized Wannier functions (see http://www.wannier.org ). !!! Notes

      * The files that are created can also be used by Wannier90 in stand-alone mode.
  * In order to use Wannier90 as a post-processing program for ABINIT you might have to
    compile it with the appropriate flags (see ABINIT makefile). You might use ./configure --enable-wannier90
  * There are some other variables related to the interface of Wannier90 and ABINIT. See [[varset:w90]].

    wfmix

Mnemonics: WaveFunctions MIXing factor
Mentioned in topic(s): topic_Hybrids
Variable type: real
Dimensions: scalar
Default value: 1.0
Only relevant if: %usefock > 0 and nnsclohf >0 and fockoptmix/100 > 0
Added in version: before_v9

Test list (click to open). Rarely used, [3/1245] in all abinit tests, [0/159] in abinit tutorials

When the wavefunctions are determined using a SCF double loop (hybrid functionals), wfmix provides the mixing factor to obtain the new input wavefunctions by the combination of the earlier input wavefunctions and corresponding (DFT-preconditioned) output wavefunctions at the level of the outer loop, according to the algorithm specified by fockoptmix/100. If wfmix is 1.0, the output wavefunctions only will determine the new input wavefunctions. This might possibly lead to instabilities. If wfmix is smaller than 1.0, the whole iteration procedure is damped, which might allow better stability, but might be slower. If it is larger than 1.0, perhaps less iterations will be needed (if there is no instability).

wtq

Mnemonics: WeighTs for the current Q-points
Mentioned in topic(s): topic_q-points
Variable type: real
Dimensions: scalar
Default value: 1
Comment: Except when qptopt/=0
Added in version: before_v9

Test list (click to open). Rarely used, [1/1245] in all abinit tests, [0/159] in abinit tutorials

Gives the current q-point weight.

wvl_bigdft_comp

Mnemonics: WaVeLet BIGDFT Comparison
Mentioned in topic(s): topic_Wavelets
Variable type: integer
Dimensions: scalar
Default value: 0
Added in version: before_v9

Test list (click to open). Moderately used, [18/1245] in all abinit tests, [0/159] in abinit tutorials

This variable is used for the wavelets capabilities of ABINIT (see usewvl). It is used to compare the results obtained with ABINIT with those obtained with BigDFT stand-alone. When it is set to 1, ABINIT will follow the workflow as in BigDFT stand-alone. Therefore, the results must be exactly the same with the two codes.

wvl_crmult

Mnemonics: WaVeLet Coarse grid Radius MULTiplier
Mentioned in topic(s): topic_Wavelets
Variable type: real
Dimensions: scalar
Default value: 6.0
Added in version: before_v9

Test list (click to open). Moderately used, [20/1245] in all abinit tests, [9/159] in abinit tutorials

This factor is used to define the expansion of the coarse resolution grid in the case of wavelets (see usewvl). The grid is made of points inside spheres centered on atoms. The radius of these spheres are the product between this factor and the covalent radius of element (read from the pseudo-potential file). This factor is responsible for the amount of used memory (see also wvl_hgrid).

wvl_frmult

Mnemonics: WaVeLet Fine grid Radius MULTiplier
Mentioned in topic(s): topic_Wavelets
Variable type: real
Dimensions: scalar
Default value: 10.0
Added in version: before_v9

Test list (click to open). Moderately used, [20/1245] in all abinit tests, [9/159] in abinit tutorials

This factor is used to define the expansion of the fine resolution grid in the case of wavelets (see usewvl). This fine resolution grid has the same grid step than the coarse one (see wvl_crmult ), but on each point, 8 coefficients are stored instead of one, increasing the precision of the calculation in this area. The grid is made of points inside spheres centered on atoms. The radius of these spheres are the product between this factor and a value read from the pseudo-potential file. This factor is responsible for the amount of used memory (see also wvl_hgrid).

wvl_ngauss

Mnemonics: WaVeLet Number of GAUSSians
Mentioned in topic(s): topic_Wavelets
Variable type: integer
Dimensions: (2)
Default value: [1, 100]
Added in version: before_v9

Test list (click to open). Rarely used, [5/1245] in all abinit tests, [0/159] in abinit tutorials

In the wavelet-PAW computation case, projectors may be fitted to a sum of complex Gaussians. The fit is done for wvl_ngauss (1), wvl_ngauss (1)+1… up to wvl_ngauss (2) Gaussians.

wvl_nprccg

Mnemonics: WaVeLet maximum Number of PReConditioner Conjugate Gradient iterations
Mentioned in topic(s): topic_Wavelets
Variable type: integer
Dimensions: scalar
Default value: 5
Added in version: before_v9

Test list (click to open). Moderately used, [17/1245] in all abinit tests, [0/159] in abinit tutorials

In the wavelet computation case, the wavefunctions are directly minimised using a real-space preconditioner. This preconditioner has internally some conjugate gradient iterations. This value defines a boundary for the number of conjugate gradient iterations on each wavefunction convergence step.

xredsph_extra

Mnemonics: X(position) in REDuced coordinates of the SPHeres for dos projection in the EXTRA set
Mentioned in topic(s): topic_printing, topic_AtomCentered
Variable type: real
Dimensions: (3,natsph_extra)
Default value: 0.0
*Only relevant if: natsph_extra > 0
Added in version: before_v9

Test list (click to open). Rarely used, [1/1245] in all abinit tests, [0/159] in abinit tutorials

The positions in reduced coordinates of extra spheres used in the DOS projection, simulating an STS signal. See natsph_extra for a more complete description.