# 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

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

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

##### Default: 1

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

### UnitsInput

##### Default: 1

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

### Verbose

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

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

##### Default: unpolarized

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

• unpolarized: Spin-unpolarized calculation.

• polarized: Spin-polarized calculation.

### XCFunctional

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

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

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

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

##### Default: 1.0

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

### TB_c

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

## Species

### NuclearCharge

##### Type: real

Nuclear charge of the species.

### Orbitals

##### Type: block data

This options sets the electronic configuration of the species. 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

##### Default: 1e-6

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

### PPOutputFileFormat

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

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

##### Default: -1

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

## Pseudopotentials tests

### PPTests

##### Default: ld+dm

What tests should be performed. Possible values are:

• ld: logarithmic derivatives.

• dm: transition dipole moments.

• ip_test: ionization potentials.

### PPTestSCF

##### Default: false

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

### PPTestOrbitals

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

##### Default: "ae"

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

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

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

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

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

Sets the starting point of the mesh.

### MeshOutmostPoint

##### Default: sqrt(NuclearCharge)*30 a.u.

Sets the outmost point of the mesh.

### MeshNumberOfPoints

##### Default: sqrt(NuclearCharge)*200)

Sets the mesh number of points.

### MeshDerivMethod

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

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

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

##### Default: 0.0

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

### ConvRelDens

##### Default: 1e-8

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

### ConvAbsEnergy

##### Default: 0.0

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

### ConvRelEnergy

##### Default: 0.0

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

### SmearingFunction

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

##### Default: broyden

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

• linear: Linear mixing.

• broyden: Broyden mixing.

### Mixing

##### Default: 0.3

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

### MixingSteps

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

##### Default: 1e-8 a.u.

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

### ODESteppingFunction

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

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.