by Andris Gulans for exciting carbon
Purpose: In this tutorial, you will learn what is a species file and what is the physics behind it.
1. What is a species file?
exciting, as a code based on plane-wave augmentation, distinguishes between the interstitial and muffin-tin regions. In the interstitial region, different quantities, such as wavefunctions, potential, and density, are described by means of plane waves. The quality (completeness) of this basis is determined by the maximum wavevector defined via either gmaxvr or rgkmax. Basis functions in the muffin-tin region are much more cumbersome to define, and thus require a detailed description. Furthermore, each muffin tin is associated with some atom with a certain nuclear charges, mass, etc. All this information is summarised in species files.
2. Content
Consider the standard species file for carbon.
<?xml version="1.0" encoding="UTF-8"?> <spdb xsi:noNamespaceSchemaLocation="../../xml/species.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <sp chemicalSymbol="C" name="carbon" z="-6.00000" mass="21894.16673"> <muffinTin rmin="0.100000E-04" radius="1.4500" rinf="21.0932" radialmeshPoints="250"/> <atomicState n="1" l="0" kappa="1" occ="2.00000" core="true"/> <atomicState n="2" l="0" kappa="1" occ="2.00000" core="false"/> <atomicState n="2" l="1" kappa="1" occ="1.00000" core="false"/> <atomicState n="2" l="1" kappa="2" occ="1.00000" core="false"/> <basis> <default type="lapw" trialEnergy="0.1500" searchE="false"/> <custom l="0" type="apw+lo" trialEnergy="0.1500" searchE="true"/> <custom l="1" type="apw+lo" trialEnergy="0.1500" searchE="true"/> </basis> </sp> </spdb>
The information contained in the first two lines is not relevant for the physics of the system: They are only used to give advanced XML instructions to define the XML language, stylesheet, and schema (for further details on this topic, see XML and exciting data format). Concerning only the physical ground of this file and putting in evidence the different blocks by adding irrelevant blank lines, the file shown above can be we can be simplified as in the following.
<spdb> <sp chemicalSymbol="C" name="carbon" z="-6.00000" mass="21894.16673"> <muffinTin rmin="0.100000E-04" radius="1.4500" rinf="21.0932" radialmeshPoints="250"/> <atomicState n="1" l="0" kappa="1" occ="2.00000" core="true"/> <atomicState n="2" l="0" kappa="1" occ="2.00000" core="false"/> <atomicState n="2" l="1" kappa="1" occ="1.00000" core="false"/> <atomicState n="2" l="1" kappa="2" occ="1.00000" core="false"/> <basis> <default type="lapw" trialEnergy="0.1500" searchE="false"/> <custom l="0" type="apw+lo" trialEnergy="0.1500" searchE="true"/> <custom l="1" type="apw+lo" trialEnergy="0.1500" searchE="true"/> </basis> </sp> </spdb>
Concerning only the physical ground of the species file, we can identify four logical segments in the above example file.
- The first segment describes the properties of the nucleus.
<sp chemicalSymbol="C" name="carbon" z="-6.00000" mass="21894.16673">
- The second segment defines the radial grid associated with the atom of this kind.
<muffinTin rmin="0.100000E-04" radius="1.4500" rinf="21.0932" radialmeshPoints="250"/>
The names of attributes are self-explanatory. rmin is the radial coordinate of the innermost grid point. radius is the default value of the muffin-tin radius. Keep in mind that it may be and frequently is overridden in the input file. rinf is the coordinate of the effective infinity. This parameter is used in calculations of atoms during the initialisation and every time core states are calculated during the self-consistency steps. Finally, radialmeshPoints defines the number of grid points in the muffin tin. In practice, there will be more points between the muffin-tin boundary and the effective infinity, but their number is calculated automatically. Even though these attributes are not further discussed here, you should be aware that the default choice is not necessarily optimal. The choice of the muffin-tin radius clearly depends on interatomic distances and is system-dependent. Also rmin and radialmeshPoints are the parameters that you may want to occasionally explore.
- The third segment introduces division into core and valence states. Once again, the names of attribute are self-explanatory. As the only exception, the meaning of the quantum number kappa in exciting is not the same as in quantum mechanics textbooks. Here, kappa adopts the absolute value of the "textbook kappa". According to the standard species file, the shell 1s2 is assigned to the core, while 2s22p2 are considered as the valence shells.
<atomicState n="1" l="0" kappa="1" occ="2.00000" core="true"/> <atomicState n="2" l="0" kappa="1" occ="2.00000" core="false"/> <atomicState n="2" l="1" kappa="1" occ="1.00000" core="false"/> <atomicState n="2" l="1" kappa="2" occ="1.00000" core="false"/>
- The fourth segment describes the muffin-tin basis.
<basis> <default type="lapw" trialEnergy="0.1500" searchE="false"/> <custom l="0" type="apw+lo" trialEnergy="0.1500" searchE="true"/> <custom l="1" type="apw+lo" trialEnergy="0.1500" searchE="true"/> </basis>
The example above specifies that apw+lo is used for the $l=0$ and $l=1$ channels. Higher $l$ are considered using lapw. The attribute trialEnergy defines initial values of the energy parameters, which are adapted during the calculations in case the parameter searchE is set to true, otherwise they are kept constant. The energy parameters are always considered on the absolute scale, and not as the distance to the Fermi energy.
3. LAPW vs. APW+lo
LAPW
The muffin-tin part of the augmented-plane-wave (APW) basis is
(1)In order to make APW accurate, the energy parameter $\varepsilon_l$ must be a very good approximation to the eigenenergies of states with angular momentum $l$. It is difficult or even impossible to arrange this in practice. To overcome this problem, the energy dependence of the basis is linearized. The radial function with the exact eigenenergy as the energy parameter $\epsilon$ is expressed as
(2)where $\dot{u}_l=\partial u_l/ \partial\epsilon$. This expression cannot be applied directly, however, it shows that the improved muffin-tin basis should contain $u_l(r;\varepsilon_l)$ and $\dot{u}_l(r;\varepsilon_l)$.
One possibility how to implant the linearization are linearized augmented plane waves (LAPW). According to LAPW, the basis functions in muffin tins are defined as
(3)where the prefactors $A^\mathbf{G+k}_{lm}$ and $B^\mathbf{G+k}_{lm}$ are chosen in a such way that $\phi_\mathbf{G+k}(\mathbf{r})$ is smooth and continuous at the muffin-tin boundary. To define the smooth (LAPW) augmentation in species, set the attribute type to "lapw". In the example below, the species file for carbon is transformed in such a way that the only augmentation type is LAPW.
<spdb> <sp chemicalSymbol="C" name="carbon" z="-6.00000" mass="21894.16673"> <muffinTin rmin="0.100000E-04" radius="1.4500" rinf="21.0932" radialmeshPoints="250"/> <atomicState n="1" l="0" kappa="1" occ="2.00000" core="true"/> <atomicState n="2" l="0" kappa="1" occ="2.00000" core="false"/> <atomicState n="2" l="1" kappa="1" occ="1.00000" core="false"/> <atomicState n="2" l="1" kappa="2" occ="1.00000" core="false"/> <basis> <default type="lapw" trialEnergy="0.15" searchE="false"/> <custom l="0" type="lapw" trialEnergy="-0.20" searchE="true"/> <custom l="1" type="lapw" trialEnergy="0.15" searchE="true"/> </basis> </sp> </spdb>
In this example, the energy parameters used for LAPW are $\varepsilon_0=-0.20$, $\varepsilon_1=0.15$ and $\varepsilon_{l>1}=0.15$. Note, however, that the attribute searchE is set to "true" for $\varepsilon_0$ and $\varepsilon_1$. It means that these two energy parameters will be updated automatically during groundstate calculations. The updated values are stored in LINENGY.OUT.
APW+lo
The alternative approach to implant the linearization is to introduce a different kind of basis functions - local orbitals. They are defined as
(4)in one particular muffin-tin and as 0 everywhere else. The example below shows how to transform your basis into APW+lo.
<spdb> <sp chemicalSymbol="C" name="carbon" z="-6.00000" mass="21894.16673"> <muffinTin rmin="0.100000E-04" radius="1.4500" rinf="21.0932" radialmeshPoints="250"/> <atomicState n="1" l="0" kappa="1" occ="2.00000" core="true"/> <atomicState n="2" l="0" kappa="1" occ="2.00000" core="false"/> <atomicState n="2" l="1" kappa="1" occ="1.00000" core="false"/> <atomicState n="2" l="1" kappa="2" occ="1.00000" core="false"/> <basis> <default type="apw" trialEnergy="0.1500" searchE="false"/> <custom l="0" type="apw+lo" trialEnergy="-0.20" searchE="true"/> <custom l="1" type="apw+lo" trialEnergy="0.15" searchE="true"/> </basis> </sp> </spdb>
This specification of the basis involves APWs for all $l$-channels. However, for $l=0$ and $1$ there are additional basis functions - local orbitals. They are requested by specifying type = "apw+lo". These local orbitals have exactly the same form as introduced above, namely, they are linear combinations of $u_l(r;\varepsilon_l)$ and $\dot{u}_l(r;\varepsilon_l)$. The energy parameters are the same as in the LAPW case.
The best of the two worlds
In practice, both APW+lo and LAPW significantly improve upon APW. While, in practice, APW+lo is more accurate than LAPW, the former methods introduces additional basis functions. Therefore, APW+lo is not practical for replacing APW for high-$l$ channels. For this reason, we recommend to use APW+lo for low $l$, and LAPW for high $l$. This strategy is implemented in the standard species files.
4. Semi-core states
The linearization procedure described above is useful for improving the description of valence states. However, local orbitals can be used also for describing semicore states.
Consider lithium atom. It has the shell structure 1s22s1, which contains just one valence electron. The 1s state can be attributed to the core, but it is neither sufficiently localized within Li muffin tins nor well separated from valence states in terms of energy. Therefore, it makes sense to consider the 1s state on the same footing as valence states. This idea is implemented in the example below that is the standard species file for Li.
<spdb> <sp chemicalSymbol="Li" name="lithium" z="-3.00000" mass="12652.66897"> <muffinTin rmin="0.100000E-04" radius="1.7000" rinf="29.9495" radialmeshPoints="250"/> <atomicState n="1" l="0" kappa="1" occ="2.00000" core="false"/> <atomicState n="2" l="0" kappa="1" occ="1.00000" core="false"/> <basis> <default type="lapw" trialEnergy="0.1500" searchE="false"/> <custom l="0" type="apw+lo" trialEnergy="0.1500" searchE="true"/> <lo l="0"> <wf matchingOrder="0" trialEnergy="0.1500" searchE="true"/> <wf matchingOrder="1" trialEnergy="0.1500" searchE="true"/> <wf matchingOrder="0" trialEnergy="-1.8784" searchE="true"/> </lo> </basis> </sp> </spdb>
The attribute core = "false" explicitly defines that 1s and 2s are supposed to be treated as valence states. Another important ingredient is the element that describes a local orbital.
<lo l="0"> <wf matchingOrder="0" trialEnergy="0.1500" searchE="true"/> <wf matchingOrder="1" trialEnergy="0.1500" searchE="true"/> <wf matchingOrder="0" trialEnergy="-1.8784" searchE="true"/> </lo>
This element consists of three subelements that describe to three "primitive" functions that satisfy the radial Schrödinger equation. The first subelement contains the attributes matchingOrder = "0" and trialEnergy = "0.1500". They mean that the first "primitive" function corresponds to the zeroth-order energy-derivative and the energy parameter is $0.15$. In other words, the first subelement corresponds to $u_0(r;0.15)$. The second subelement contains matchingOrder = "1". It means that the second "primitive" function is the first energy-derivative $\dot{u}_0(r;0.15)$. Finally, the third function is $u_0(r;-1.8784)$.
The local orbital is defined as a linear combination of these primitive functions:
(5)where $l$, $\varepsilon_l\,$, and $\varepsilon_\mathrm{lo}$ are of the values listed above. The prefactors $a_\nu\,$, $b_\nu\,$, and $c_\nu$ are automatically chosen in a such way that the local orbital normalizes to 1 and turns to 0 at the muffin-tin boundary. These two conditions are essential and are employed for all local orbitals. In order to be able to determine $a_\nu\,$, $b_\nu\,$, and $c_\nu$ uniquely, the third condition is that the radial derivative of the local orbital turns to 0 at the muffin-tin boundary.