Input

APE has quite a few options, that we will subdivide in different groups. After the name of the option, its type and default value (when applicable) are also given. Do not be scared by the amount of options! For many calculations you can safely rely on the default values of most of the options.

The parser

All input options should be in a file called inp.ape, in the directory APE is run from. It is also possible to use a file with a different name. In that case the standard input should redirect to that file. For example, in bash:

ape < filename

For fairly comprehensive examples, just look at the files in the APE_HOME/samples directory.

At the beginning of the program the oct_parser library reads the inp.ape file, parses it, and generates a list of variables that will be read by APE (note that the input is case independent). There are two kind of variables, scalar values (strings or numbers), and blocks (that you may view as matrices). A scalar variable var can be defined by:

var = exp

var can contain any alphanumeric character plus "_", and exp can be a quote delimited string, a number (integer, real, or complex), a variable name, or a mathematical expression. In the expressions all arithmetic operators are supported (a+b, a-b, a*b, a/b; for exponentiation the C syntax a^b is used), and the following functions can be used:

  • sqrt(x): The square root of x.

  • exp(x): The exponential of x.

  • log(x) or ln(x): The natural logarithm of x.

  • log10(x): Base 10 logarithm of x.

  • sin(x), cos(x), tan(x), cot(x), sec(x), csc(x): The sinus, co-sinus, tangent, co-tangent, secant and co-secant of x.

  • asin(x), acos(x), atan(x), acot(x), asec(x), acsc(x): The inverse (arc-) sinus, co-sinus, tangent, co-tangent, secant and co-secant of x.

  • sinh(x), cosh(x), tanh(x), coth(x), sech(x), csch(x): The hyperbolic sinus, co-sinus, tangent, co-tangent, secant and co-secant of x.

  • asinh(x), acosh(x), atanh(x), acoth(x), asech(x), acsch(x): The inverse hyperbolic sinus, co-sinus, tangent, co-tangent, secant and co-secant of x.

You can also use any of the predefined variables:

  • pi: 3.141592653589793, what else is there to say?

  • e: The base of the natural logarithms.

  • false or f or no: False in all its flavors. For the curious, false is defined as 0.

  • true or t or yes: The truthful companion of false. For the curious, true is defined as 1.

Blocks are defined as a collection of values, organized in row and column format. The syntax is the following:

%var
  exp | exp | exp | ...
  exp | exp | exp | ...
 ...
%

Rows in a block are separated by a newline, while columns are separated by the character "|" or by a tab. There may be any number of lines and any number of columns in a block. Note also that each line can have a different number of columns.

If APE tries to read a variable that is not defined in the inp.ape file, it automatically assigns to it a default value. All variables read are output to the file parser.log. If you are not sure of what the program is reading, just take a look at it. Everything following the character "#" until the end of the line is considered a comment and is simply cast into oblivion.

Generalities

CalculationMode

Type: flag
Default: ae+pp

It defines the type of calculation to perform. Options are:

  • ae: Atomic calculation.

  • pp: Pseudopotential generation.

  • pp_test: Pseudopotential test.

  • xc: One-shot evaluation of exchange and correlation energies and potentials and/or kinetic energy density functionals.

  • ip: Calculation of ionization energy.

  • nt: Numerical tests. Should only be useful to developers.

Units

Type: integer
Default: 1

Internally, the code works in atomic units. However, you can use this option to define the units used in the input and output files.

Valid options are:

  • 1: atomic units.

  • 2: atomic Rydberg units.

  • 3: electron-volts/ångström.

UnitsOutput

Type: integer
Default: 1

Same as Units, but only refers to the values in the output files.

UnitsInput

Type: integer
Default: 1

Same as Units, but only refers to the values in the input file.

Verbose

Type: integer
Default: 30

Verbosity level of the program. The higher, the more verbose APE is. Current levels are:

  • verbose $\le 0$: Silent mode. No output except fatal errors.

  • verbose $\gt 0$: Warnings only.

  • verbose $\gt 10$: Important program info only.

  • verbose $\gt 20$: Normal program info.

  • verbose $\gt 30$: Normal program info plus detailed info about the SCF cycle.

Hamiltonian

These parameters control what Hamiltonian to use when solving the Khon-Sham equations.

WaveEquation

Type: integer
Default: schrodinger

When performing atomic calculations APE can solve either the Kohn-Sham equations, the Dirac-Kohn-Sham equations or the scalar-relativistic Khon-Sham equations. Valid options are:

  • schrodinger: Kohn-Sham equations.

  • dirac: Dirac-Kohn-Sham equations.

  • scalar_rel: scalar-relativistic Kohn-Sham equations.

SpinMode

Type: integer
Default: unpolarized

Defines the spin mode APE will run in. Valid modes are:

  • unpolarized: Spin-unpolarized calculation.

  • polarized: Spin-polarized calculation.

XCFunctional

Type: integer
Default: lda_x + lda_c_pw

The possible values are (note that, depending on the version of Libxc used, some of the following functionals might not be available):

  • none: No exchange-correlation.

  • lda_x: Slater exchange.

  • lda_c_wigner: Wigner parametrization.

  • lda_c_rpa: Random Phase Approximation.

  • lda_c_hl: Hedin & Lundqvist.

  • lda_c_gl: Gunnarson & Lundqvist.

  • lda_c_xalpha: Slater’s Xalpha.

  • lda_c_vwn: Vosko, Wilk, & Nussair.

  • lda_c_vwn_rpa: Vosko, Wilk, & Nussair (fit to the RPA correlation energy).

  • lda_c_pz: Perdew & Zunger.

  • lda_c_pz_mod: Perdew & Zunger (Modified to improve the matching between the high and the low rs region).

  • lda_c_ob_pz: Ortiz & Ballone (PZ-type parametrization).

  • lda_c_pw: Perdew & Wang.

  • lda_c_pw_mod: Perdew & Wang (Modified to match the original PBE routine).

  • lda_c_ob_pw: Ortiz & Ballone (PW-type parametrization).

  • lda_c_vbh: von Barth & Hedin.

  • lda_c_ml1: Modified LSD (version 1) of Proynov and Salahub.

  • lda_c_ml2: Modified LSD (version 2) of Proynov and Salahub.

  • lda_xc_teter93: Teter 93.

  • gga_x_pbe: Perdew, Burke & Ernzerhof.

  • gga_x_pbe_r: Perdew, Burke & Ernzerhof (revised).

  • gga_x_p86: Becke 86 Xalpha,beta,gamma.

  • gga_x_b86_r: Becke 86 Xalpha,beta,gamma reoptimized.

  • gga_x_b86_mgc: Becke 86 Xalpha,beta,gamma (with mod. grad. correction).

  • gga_x_b88: Becke 88.

  • gga_x_g96: Gill 96.

  • gga_x_pw86: Perdew & Wang 86.

  • gga_x_pw91: Perdew & Wang 91.

  • gga_x_optx: Handy & Cohen OPTX 01.

  • gga_x_dk87_r1: dePristo & Kress 87 (version R1).

  • gga_x_dk87_r2: dePristo & Kress 87 (version R2).

  • gga_x_lg93: Lacks & Gordon 93.

  • gga_x_ft97_a: Filatov & Thiel 97 (version A).

  • gga_x_ft97_b: Filatov & Thiel 97 (version B).

  • gga_x_pbe_sol: Perdew, Burke & Ernzerhof exchange (solids).

  • gga_x_rpbe: Hammer, Hansen & Norskov (PBE-like).

  • gga_x_wc: Wu & Cohen

  • gga_x_mpw91: mPW91 of Adamo & Barone.

  • gga_x_am05: Armiento & Mattsson 05 exchange.

  • gga_x_pbea: Madsen 07.

  • gga_x_mpbe: Adamo & Barone modification to PBE.

  • gga_x_xpbe: Extended PBE by Xu & Goddard III.

  • gga_x_bayesian: Bayesian best fit for the enhancement factor.

  • gga_x_pbe_jsjr:

  • gga_x_optb88_vdw: opt-Becke 88 for vdW.

  • gga_x_pbek1_vdw: Reparametrized PBE for vdW.

  • gga_x_optpbe_vdw: Reparametrized PBE for vdW.

  • gga_x_rge2: Regularized PBE.

  • gga_c_pbe: Perdew, Burke & Ernzerhof correlation.

  • gga_c_lyp: Lee, Yang, & Parr LDA.

  • gga_c_pbe_sol: Perdew, Burke & Ernzerhof correlation SOL.

  • gga_c_p86: Perdew 86.

  • gga_c_pw91: Perdew & Wang 91.

  • gga_c_am05: Armiento & Mattsson 05 correlation.

  • gga_c_xpbe: Extended PBE by Xu & Goddard III.

  • gga_c_lm: Langreth & Mehl.

  • gga_c_pbe_jrgx: Reparametrized PBE by Pedroza, Silva & Capelle.

  • gga_c_rge2: Regularized PBE.

  • gga_xc_lb: van Leeuwen & Baerends.

  • gga_xc_hcth_93: HCTH functional fitted to 93 molecules.

  • gga_xc_hcth_120: HCTH functional fitted to 120 molecules.

  • gga_xc_hcth_147: HCTH functional fitted to 147 molecules.

  • gga_xc_hcth_407: HCTH functional fitted to 407 molecules.

  • gga_xc_edf1: Empirical functionals from Adamson, Gill, and Pople.

  • gga_xc_xlyp: XLYP functional.

  • gga_xc_b97: Becke 97.

  • gga_xc_b97_1: Becke 97-1.

  • gga_xc_b97_2: Becke 97-2.

  • gga_xc_b97_d: Becke 97-D (Grimme functional to be used with C6 vdW term).

  • gga_xc_b97_k: Becke 97-K (Boese-Martin for Kinetics).

  • gga_xc_b97_3: Becke 97-3.

  • gga_xc_pbe1w: PBE1W (functional fitted for water).

  • gga_xc_mpwlyp1w: mPWLYP1w (functional fitted for water).

  • gga_xc_pbelyp1w: PBELYP1W (functional fitted for water).

  • gga_xc_sb98_1a: SB98 (1a).

  • gga_xc_sb98_1b: SB98 (1b).

  • gga_xc_sb98_1c: SB98 (1c).

  • gga_xc_sb98_2a: SB98 (2a).

  • gga_xc_sb98_2b: SB98 (2b).

  • gga_xc_sb98_2c: SB98 (2c).

  • mgga_x_bj06: Becke & Johnson 06.

  • mgga_x_tb09: Tran & Blaha 09.

  • mgga_x_rpp09: Rasanen, Pittalis & Proetto 09.

XCCorrections

Type: integer
Default: none

The possible values are:

  • none: no corrections.

  • rel_x: relativistic correction to the exchange functional (implementd only for LDA exchange).

  • rel_c: relativistic correction to the correlation functional (not yet implemented).

  • adsic: averaged density self-interaction correction.

KEDFunctional

Type: integer
Default: none

Kinetic energy density functional. This is only used when running the xc calculation mode. For a complete list of available functionals, check the Libxc documentation.

TheoryLevel

Type: integer
Default: dft

The possible values are:

  • independent_particles: particles are considered as independent, i.e. as non-interacting.

  • dft: this is the default density-functional theory scheme.

Xalpha

Type: real
Default: 1.0

Sets the value of the alpha parameter when using Slater’s Xalpha functional (lda_c_xalpha).

TB_c

Type: real
Default: 1.0

Fixes the value of the c parameter to a given value when using the Tran-Blaha functional (mgga_x_tb09). If the value is set to 1.0, then the parameter is calculated in the usual way. Note that c=1.0 gives the Becke & Johnson 06 functional (mgga_x_bj06).

Specie

NuclearCharge

Type: real

Nuclear charge of the specie.

Orbitals

Type: block data
Default:

This options sets the electronic configuration of the specie. To each line corresponds an orbital, which is defined by some quantum numbers and its occupancy.

The first and second columns are the main quantum number $n$ and the angular momentum quantum number $l$. The meaning of the remaining columns depends if we are running a fully-relativistic spin-polarized calculation or not. In the later case, the remaining columns are used to specify the occupancies. One or two columns can be used to specify the occupancies and there are four possible cases:

  • The calculation is spin-unpolarized and only the third column is set: the occupancy of the orbital is simply set by the third column.

  • The calculation is spin-unpolarized and the third and fourth columns are set: the occupancy of the orbital is equal to the sum of both columns.

  • The calculation is spin-polarized and only the third column is set: the occupancies of the two spin channels are equal to half the value of the third column.

  • The calculation is spin-polarized and the third and fourth columns are set: the occupancies of the two spin channels are set by the two columns.

When running a fully-relativistic spin-polarized calculation (WaveEquation = dirac and SpinMode = polarized), besides the $n$ and $l$ quantum numbers, it is also necessary to specify the $m$ quantum number, which will always be the third column of the block. This quantum number runs from $-j$ to $j$, where $j$ can have two values: $j = l - 1/2$ and $j = l + 1/2$. This means that, when $|m| \lt l+1/2$ there will be two orbitals with the same $m$ quantum number. To differentiate these two orbitals, a fourth quantum number is introduced, which can have two values: up or down (these are represented in APE by $0.5$ and $-0.5$). The meaning of the columns beyond the third is thus the following:

  • If $|m| = 2l+1$: the fourth column is just the occupancy.

  • If $|m| \lt 2l+1$: the fourth column is the occupancy of the up orbital and the fifth column is the occupancy of the down orbital. If only the fourth column is set, both orbitals are equally occupied with half the specified value.

Note that the occupancies can be set to zero.

Here is an example for the Lithium ground state electronic configuration:

 %Orbitals
  1 | 0 | 1 | 1
  2 | 0 | 1 | 0
  2 | 1 | 0 | 0
%

The first column sets the quantum number $n$, the second the quantum number $l$ and the last two the occupancies for both spin channels. In case of a fully-relativistic spin-polarized calculation, the previous example would become:

%Orbitals
  1 | 0 | -1/2 | 1
  1 | 0 |  1/2 | 1
  2 | 0 | -1/2 | 1
  2 | 0 |  1/2 | 0
  2 | 1 | -3/2 | 0
  2 | 1 | -1/2 | 0 | 0
  2 | 1 |  1/2 | 0 | 0
  2 | 1 |  3/2 | 0
%

To make things easier, the core configuration can be replaced by a string with the chemical symbol of the rare gas that has the same configuration. For example, to run Sodium, it is possible to use the following input:

%Orbitals
  "Ne"
  3 | 0 | 1
%

Pseudopotentials generation

PPComponents

Type: block data

This block sets which pseudopotential components will be generated and the corresponding core radii. The first column is the main quantum number $n$, the second column is the angular momentum quantum number $l$, the one before the last is the core radius, and the last is the scheme to be used for constructing the pseudopotentials.

When generating relativistic pseudopotentials, the third column will be the total angular momentum quantum number $j$. Nevertheless, it is possible to omit $j$, in which case both $j=l-1/2$ and $j=l+1/2$ components will use the same core radius.

Here is an example:

%PPComponents
  5 | 0 | 1.0 | tm
  5 | 1 | 0.5 | 1.4 | tm
  5 | 1 | 1.5 | 1.6 | tm
  4 | 2 | 2.0 | tm
%

In this case, the $j=l-1/2$ and $j=l+1/2$ components of $l=1$ will have different core radius, while for $l=2$ they will have the same core radius.

Note that it is possible to set the core-radii to zero. In that case, APE will use some default value that depends on which scheme is used for constructing the pseudopotentials. Right now, this feature only works with the Hamann scheme. In that case the default core-radius is determined using the value of the outermost maximum of the all-electron wavefunction. If there are core states present with the same angular momentum the default core-radius is equal to 0.6 times the outermost maximum. Otherwise, the core radius is 0.4 times the outermost maximum.

The possible values for the scheme used for constructing the pseudopotentials are:

  • ham: Hamann scheme.

  • tm: Troullier-Martins scheme.

  • rtm: Relativistic extension of the Troullier-Martins scheme.

  • mrpp: MRPP scheme.

Note that when using the MRPP scheme, the quantum numbers should correspond to a semi-core orbital, i.e., there should be at least another orbital with the same $l$ and $j$ quantum numbers, but higher in energy.

PPCalculationTolerance

Type: real
Default: 1e-6

This tolerance is used during the pseudopotential generation. What it does exactly depends on the pseudopotential generation scheme used.

PPOutputFileFormat

Type: integer
Default: upf

APE can write the pseudopotentials in different formats compatible with other programs. Programs currently supported are:

  • siesta: SIESTA format.

  • fhi: fhi98PP pseudopotential generator format.

  • abinit5: ABINIT format 5.

  • abinit6: ABINIT format 6.

  • upf: Quantum-Espresso unified pseudopotential format.

  • parsec: parsec format. This is basically the SIESTA format plus the pseudo-wavefunctions.

  • latepp_so : LATEPP format. Spin-orbit difference potentials and respective wavefunctions for the spin-orbit treatment in the LATEPP code.

CoreCorrection

Type: integer
Default: 1

Scheme for constructing the partial core density. Possible values are:

  • 0: no non-linear core corrections.

  • 1: scheme implemented in José Luis Martins atom code.

  • 2: scheme implemented in the fhi98PP code.

LLocal

Type: integer
Default: -1

Angular momentum component of the pseudo-potentential to take as local component when building the Kleinman-Bylander projectros. If set to -1 a Vanderbilt function is used.

Pseudopotentials tests

PPTests

Type: integer
Default: ld+dm

What tests should be performed. Possible values are:

  • ld: logarithmic derivatives.

  • dm: transition dipole moments.

  • ip_test: ionization potentials.

PPTestSCF

Type: logical
Default: false

If set to yes, run a SCF calculation for the pseudostates before performing the tests.

PPTestOrbitals

Type: block data
Default:

Orbitals configuration to be used for the SCF calculation performed when PPTestSCF is set ot yes. This allows to change the occupancies of the valence states or to add other states to be tested.

PPTestAEDir

Type: string
Default: "ae"

Directory where to find the all-electron calculations that should be used during the tests. The default is the ae directory.

LogDerivativeRadius

Type: real
Default: 0.0

Diagnostic radius where the logarithmic derivatives are computed. If set to zero, APE will use the element covalent radius.

LogDerivativeEnergyMax

Type: real

Upper bound of the energy interval where the logarithmic derivatives are computed. If it is not set, then the value to be used will be equal to the largest eigenvalue plus 1 a.u.

LogDerivativeEnergyMin

Type: real

Lower bound of the energy interval where the logarithmic derivatives are computed. If it is not set, then the value to be used will be equal to the smallest eigenvalue minus 1 a.u.

LogDerivativeEnergyStep

Type: real
Default: 0.0 a.u.

Step in energy interval. If set to zero, an adaptive step will be used.

Mesh

APE uses a mesh to store functions. In order to change the mesh parameters you can use the following options:

MeshType

Type: integer
Default: log1

Possible values are:

  • lin: Linear

  • log1: Logarithmic, defined as $r_i = b \, e^{a \, i}$

  • log2: Logarithmic, defined as $r_i = b \; (e^{a \, i} - 1)$

MeshStartingPoint

Type: real
Default: sqrt(NuclearCharge)*1e-5 a.u.

Sets the starting point of the mesh.

MeshOutmostPoint

Type: real
Default: sqrt(NuclearCharge)*30 a.u.

Sets the outmost point of the mesh.

MeshNumberOfPoints

Type: integer
Default: sqrt(NuclearCharge)*200)

Sets the mesh number of points.

MeshDerivMethod

Type: integer
Default: cubic_spline

Numerical method used to compute derivatives. Possible choices are:

  • cubic_spline: Use cubic splines to interpolate the function and then uses this interpolation to compute the derivatives.

  • finite_diff: Finite differences. The number of points used is controled by the MeshFiniteDiffOrder variable.

MeshFiniteDiffOrder

Type: integer
Default: 4

This variable controls the numbers of points used for the finite differences discretization. To compute the derivative at a given point, the finite difference formula will use MeshFiniteDiffOrder points to the left and MeshFiniteDiffOrder points to the right. This means that in total MeshFiniteDiffOrder$*2 + 1$ points will be used.

SCF

The self consistent field procedure will stop when one of the convergence criteria is fulfilled. At each iteration the new guess potential is built mixing the input and output potentials.

MaximumIter

Type: integer
Default: 300

Maximum number of SCF iterations. When that number is reached the SCF procedure will stop, even if none of the criteria are fulfilled, and the calculation will continue as normal. 0 means unlimited.

ConvAbsDens

Type: real
Default: 0.0

Absolute convergence of the density. 0 means do not use this criterion.

ConvRelDens

Type: real
Default: 1e-8

Relative convergence of the density. 0 means do not use this criterion.

ConvAbsEnergy

Type: real
Default: 0.0

Absolute convergence of the total energy. 0 means do not use this criterion.

ConvRelEnergy

Type: real
Default: 0.0

Relative convergence of the total energy. 0 means do not use this criterion.

SmearingFunction

Type: integer
Default: fixed_occ

Select how the states should be occupied. The option are:

  • fixed_occ: the occupancies of the states are fixed.

  • semiconducting: semiconducting occupancies, i.e., the lowest lying states are occupied until no more electrons are left

  • averill_painter: F.W. Averill and G.S. Painter, Phys. Rev. B 46, 2498 (1992)

MixingScheme

Type: integer
Default: broyden

Selects the mixing procedure to be used during the SCF cycle. Possible values are:

  • linear: Linear mixing.

  • broyden: Broyden mixing.

Mixing

Type: real
Default: 0.3

Determines the amount of the new potential which is to be mixed with the old one.

MixingSteps

Type: integer
Default: 3

Number of steps used by Broyden mixing to extrapolate the new potential.

Wave-equations solver

APE solves the Schrodinger and Dirac equations using the ODE solver from gsl.

EigenSolverTolerance

Type: real
Default: 1e-8 a.u.

The eigensolver will improve the eigenvalues untill the error estimate of each eigenvalue is smaller than this tolerance.

ODEIntTolerance

Type: real
Default: 1e-12

ODESteppingFunction

Type: integer
Default: rkpd8

Possible values are:

  • rk2: Embedded 2nd order Runge-Kutta method

  • rk4: 4th order (classical) Runge-Kutta method

  • rkf4: Embedded 4th order Runge-Kutta-Fehlberg method

  • rkck4: Embedded 4th order Runge-Kutta Cash-Karp method

  • rkpd8: Embedded 8th order Runge-Kutta Prince-Dormand method

For more information about the stepping functions please refer to the gsl documentation.

ODEMaxSteps

Type: integer
Default: 500000

Sometimes it may happen that the ODE solver takes too many steps, because of some problem. To avoid that, APE will issue a fatal error if the number of steps is greater than ODEMaxSteps.