Pawxml
Source authors:
{{{authors}}}
License: {{{license}}}
}}{{#if: Download: {{{download}}}
}}{{#if: Documentation: {{{documentation}}}
}}{{#if:Functionalities:
Algorithms:
 {{{algorithms}}}
Generic interfaces:
 {{{generic interfaces}}}
APIs:
 {{{apis}}}
Data standards:
 {{{data standards}}}
Software:
 {{{software}}}
Contents
 1 XML specification for atomic PAW datasets
 1.1 Introduction
 1.2 What defines a dataset?
 1.3 Specification of the elements
 1.4 The header
 1.5 A comment
 1.6 The atom element
 1.7 Exchangecorrelation
 1.8 Generator
 1.9 Energies
 1.10 Valence states
 1.11 Radial grids
 1.12 Shape function for the compensation charge
 1.13 Radial functions
 1.14 Zero potential
 1.15 The KresseJoubert formulation
 1.16 Kinetic energy differences
 1.17 MetaGGA
 1.18 Exact exchange integrals
 1.19 Optional elements
 1.20 End of the dataset
 1.21 How to use the datasets
 1.22 Plotting the radial functions
 1.23 References
XML specification for atomic PAW datasets
Current version of the PAW XML specification: 0.7
Codes implementing the PAW XML format:
gpaw,
abinit,
atompaw
Introduction
This page contains information about the PAWXML data format for the atomic datasets necessary for doing Projector AugmentedWave calculations ^{[1]}. We use the term dataset instead of pseudopotential because the PAW method is not a pseudopotential method.
An example XML file for nitrogen PAW dataset using LDA can be seen here: n.lda.xml
 Note: Hartree atomic units are used in the XML file (
h= m = e = 1).
What defines a dataset?
The following quantities define a minimum PAW dataset (the notation from Ref. ^{[2]} is used here):
Quantity  Description 
Atomic number  
Exchangecorrelation functional  
Kinetic energy of the core electrons  
Shape function for compensation charge  
Allelectron core density  
Pseudo electron core density  
Pseudo electron valence density  
Zero potential  
Allelectron partial waves  
Pseudo partial waves  
Projector functions  
Kinetic energy differences 
The following quantities can be optionally provided:
Quantity  Description 
Radius of the PAW augmentation region (max. of matching radii)  
KresseJoubert local ionic pseudopotential  
Statedependent shape function for compensation charge  
Core kinetic energy density  
Pseudo core kinetic energy density  
Corecore contribution to exact exchange  
Corevalence exactexchange correction matrix 
Specification of the elements
An element looks like this:
<name> ... </name>
or for an empty element:
<name/>
 Tip: An XMLtutorial can be found here
The header
The first two lines should look like this:
<?xml version="1.0"?> <paw_dataset version="0.7">
The first line must be present in all XML files.
Everything else is put inside an element with name paw_dataset
,
and this element has an attribute called version
.
A comment
It is recommended to put a comment giving the units and a link to this web page:
<! Nitrogen dataset for the Projector Augmented Wave method. > <! Units: Hartree and Bohr radii. > <! http://www.where.org/paw_dataset.html >
The atom
element
<atom symbol="N" Z="7" core="2" valence="5"/>
The atom
element has attributes symbol
, Z
, core
and valence
(chemical symbol, atomic number, number of core electrons
and number of valence electrons).
Exchangecorrelation
The xc_functional
element defines the exchangecorrelation functional used for generating the dataset.
It has the two attributes type
and name
.
The type
attribute can be LDA
, GGA
, MGGA
or HYB
.
The name
attribute designates the exchangecorrelation functional and can be specified in the following ways:

Taking the names from the LibXC library.
The correlation and exchange names are stripped from their
XC_
part and combined with a+
sign. Here is an example for an LDA functional:<xc_functional type="LDA", name="LDA_X+LDA_C_PW"/>
and this is what PBE will look like:
<xc_functional type="GGA", name="GGA_X_PBE+GGA_C_PBE"/>

Using one of the following predefined aliases:
type name LibXC equivalent Reference LDA
PW
LDA_X+LDA_C_PW
LDA exchange; Perdew, Wang, PRB 45, 13244 (1992) GGA
PW91
GGA_X_PW91+GGA_C_PW91
Perdew et al PRB 46, 6671 (1992) GGA
PBE
GGA_X_PBE+GGA_C_PBE
Perdew, Burke, Ernzerhof, PRL 77, 3865 (1996) GGA
RPBE
GGA_X_RPBE+GGA_C_PBE
Hammer, Hansen, Nørskov, PRB 59, 7413 (1999) GGA
revPBE
GGA_X_PBE_R+GGA_C_PBE
Zhang, Yang, PRL 80, 890 (1998) GGA
PBEsol
GGA_X_PBE_SOL+GGA_C_PBE_SOL
Perdew et al, PRL 100, 136406 (2008) GGA
AM05
GGA_X_AM05+GGA_C_AM05
Armiento, Mattsson, PRB 72, 085108 (2005) GGA
BLYP
GGA_X_B88+GGA_C_LYP
Becke, PRA 38, 3098 (1988); Lee, Yang, Parr, PRB 37, 785 (1988) Examples:
<xc_functional type="LDA", name="PW"/>
<xc_functional type="GGA", name="PBE"/>
Generator
<generator type="scalarrelativistic" name="MyGenerator2.0"> Frozen core: [He] </generator>
This element contains character data describing in words how the dataset was generated.
The type
attribute must be one of: nonrelativistic
, scalarrelativistic
or relativistic
.
Energies
<ae_energy kinetic="53.777460" xc="6.127751" electrostatic="101.690410" total="54.040701"/> <core_energy kinetic="43.529213"/>
The kinetic energy of the core electrons, , is used in the PAW method. The other energies are convenient to have for testing purposes and can also be useful for checking the quality of the underlying atomic calculation.
Valence states
<valence_states> <state n="2" l="0" f="2" rc="1.10" e="0.6766" id="N2s"/> <state n="2" l="1" f="3" rc="1.10" e="0.2660" id="N2p"/> <state l="0" rc="1.10" e=" 0.3234" id="Ns1"/> <state l="1" rc="1.10" e=" 0.7340" id="Np1"/> <state l="2" rc="1.10" e=" 0.0000" id="Nd1"/> </valence_states>
The valence_states
element contains several state
elements,
defined by a unique id
as well as l
and n
quantum numbers.
For each of them it is also required to provide the energy e
,
the occupation f
and the matching radius of the partial waves rc
.
The number of state
elements determines the size of the partial wave basis. It is equal to the number of radial functions
(radial parts of the , and )
and is noted in the rest of this document.
For this dataset, the first two lines describe bound eigenstates with occupation numbers
and principal quantum numbers. Notice, that the three additional unbound states should have
no f
and n
attributes.
In this way, we know that only the first two bound states (with f
and n
attributes)
should be used for constructing an initial guess for the wave functions.
Radial grids
There can be one or more definitions of radial grids.
Example:
<radial_grid eq="r=d*i" d="0.1" istart="0" iend="9" id="g1"> <values> 0.0 0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9 </values> <derivatives> 0.1 0.1 0.1 0.1 0.1 0.1 0.1 0.1 0.1 0.1 </derivatives> </radial_grid>
This defines one radial grid as where i runs from 0 to 9.
Inside the <radial_grid>
element we have the 10 values of
followed by the 10 values of the derivatives .
All functions (densities, potentials, ...) that use this grid are given as 10 numbers defining the radial part of the function. The radial part of the function must be multiplied by a spherical harmonics:
Each radial grid has a unique id:
<radial_grid eq="r=d*i" d="0.01" istart="0" iend="99" id="lin"> <radial_grid eq="r=a*exp(d*i)" a="1.056e4" d="0.05" istart="0" iend="249" id="log">
and each numerical function must refer to one of these ids:
<function grid="lin"> ... ... </function>
In this example, the function
element should contain 100 numbers (i = 0, ..., 99).
Each number must be separated by a <newline>
character or by one or
more <tab>
's or <space>
's (no commas).
For numbers with scientific notation, use this format: 1.23456e5
or 1.23456E5
and not 1.23456D5
.
A program can read the values for and from the file
or evaluate them from the eq
and associated parameter attributes.
There are currently six types of radial grids:
eq  parameters 
r=d*i

d

r=a*exp(d*i)

a and d

r=a*(exp(d*i)1)

a and d

r=a*i/(1b*i)

a and b

r=a*i/(ni)

a and n

r=(i/n+a)^5/aa^4

a and n

The istart
and iend
attributes indicating the range of i should always be present.
Although it is possible to define as many radial grids as desired, it is recommended to minimize the number of grids in the dataset.
Shape function for the compensation charge
The general formulation of the compensation charge uses an expansion over the partial waves ij and the spherical harmonics:
where is a Gaunt coefficient.
The standard expression ^{[1]} for the shape function
is a product of the multipole moment and a shape function :
Several formulations ^{[1]}^{[3]} define
, where is an independent shape function:
type  parameters  k(r) 
gauss

rc


sinc

rc


exp

rc and lamb

Example:
<shape_function type="gauss" rc="3.478505426185e01">
Another formulation ^{[4]} defines directly :
type  parameters  g_{l}(r) 
bessel

rc

For bessel
the four parameters
(, ,
, )
must be determined from rc
for each value of as described in ^{[4]}.
Example:
<shape_function type="bessel" rc="3.478505426185e01">
There is also a more general formulation where
is given in a numerical form. Several shape functions can be set (with the <shape_function>
tag),
depending on and/or combinations of partial waves (specified using the optional state1
and state2
attributes).
See for instance section II.C of ^{[5]}.
Example 1, defining numerically in :
<shape_function type="numeric" l=0 grid="g1"> ... ... </shape_function>
Example 2, defining directly for states
=N2s
and =N2p
, and =0:
<shape_function type="numeric" l=0 state1="N2s" state2="N2p" grid="g1"> ... ... </shape_function>
Radial functions
Continuing, we have now reached the allelectron (resp. pseudo core, pseudo valence) density:
<ae_core_density grid="g1"> 6.801207147443e+02 6.801207147443e+02 6.665042896724e+02 ... ... </ae_core_density> <pseudo_core_density rc="1.1" grid="g1"> ... ... </pseudo_core_density> <pseudo_valence_density rc="1.1" grid="g1"> ... ... </pseudo_valence_density>
The numbers inside the ae_core_density
(resp. pseudo_core_density
,
pseudo_valence_density
) element defines the radial part of
(resp. , ).
The radial part must be multiplied by to get the full density
( should integrate to the number of core electrons).
The pseudo core density and the pseudo valence density are defined similarly and
also have a rc
attribute specifying the matching radius.
The ae_partial_wave
, pseudo_partial_wave
and projector_function
elements contain the radial parts of the ,
and
functions for the state
s listed in the valence_states
element above
(five states in the nitrogen example).
All functions must have an attribute state="..."
referring to one of the
states listed in the valence_states
element:
<ae_partial_wave state="N2s" grid="g1"> 8.178800366898029e+00 8.178246914143839e+00 8.177654917302689e+00 ... ... </ae_partial_wave> <pseudo_partial_wave state="N2s" grid="g1"> ... ... </pseudo_partial_wave> <projector_function state="N2s" grid="g1"> ... ... </projector_function> <ae_partial_wave state="N2p" grid="g1"> ... ... </ae_partial_wave>
Remember that the radial part of these functions must be multiplied by a spherical harmonics:
Zero potential
The zero potential, (see section VI.D of ^{[1]})
is defined similarly to the densities; the radial part must be multiplied by
to get the full potential.
The zero_potential
element has a rc
attribute specifying the cutoff
radius of ::
<zero_potential rc="1.1" grid="g1"> ... ... </zero_potential>
The KresseJoubert formulation
The KresseJoubert formulation of the PAW method ^{[4]} is very similar to the original formulation of Blöchl ^{[1]}. However, the KresseJoubert formulation does not use directly, but indirectly through the local ionic pseudopotential, . Therefore, the following transformation is necessary:
where is the number of core electrons,
is the number of valence electrons,
is the number of electrons contained in the pseudo core density and
is the number of electrons contained in the pseudo valence density.
The Hartree potential from the density n is defined as:
where is the larger of and .
 Note: In the KresseJoubert formulation, the symbol is used for what we here call and in the Blöchl formulation, we have .
It is also possible to add an element kresse_joubert_local_ionic_pseudopotential
that contains the function directly,
so that no conversion is necessary:
<kresse_joubert_local_ionic_pseudopotential rc="1.3" grid="log"> ... ... </kresse_joubert_local_ionic_pseudopotential>
The kresse_joubert_local_ionic_pseudopotential
element has a rc
attribute specifying the matching radius. This matching radius corresponds to the maximum
of all the matching radii used in the formalism.
Kinetic energy differences
<kinetic_energy_differences> 1.744042161013e+00 0.000000000000e+00 2.730637956456e+00 ... ... <kinetic_energy_differences>
This element contains the symmetric matrix:
where is the kinetic energy operator used by the generator.
With partial waves (see definition), we have a matrix listed as numbers.
MetaGGA
Datasets for use with MGGA functionals must also include information on the core kinetic energy density and pseudo core kinetic energy density ; the latters are defined with these two elements:
<ae_core_kinetic_energy_density grid="g1"> ... ... </ae_core_kinetic_energy_density> <pseudo_core_kinetic_energy_density rc="1.1" grid="g1"> ... ... </pseudo_core_kinetic_energy_density>
These densities are defined similarly to the core and valence densities (see above).
The pseudo_core_kinetic_energy_density
element has a rc
attribute
specifying its matching radius.
Exact exchange integrals
The corecore contribution to the exact exchange energy and the symmetric corevalence PAWcorrection matrix are given as:
The coefficients depend only
on pairs of the radial basis functions
and can be evaluated by summing over radial integrals times 3j symbols
according to:
where
is the number of core electrons corresponding to , namely ,
(resp. ) is the larger (resp. smaller) of and .
can be specified in the core
attribute of the <exact_exchange>
element.
With valence states
(see definition),
is a matrix.
It can be specified as numbers inside
the <exact_exchange>
element:
<exact_exchange core="..."> ... ... </exact_exchange>
Optional elements
<paw_radius rc="2.3456781234">
Although not necessary, it may be helpful to provide the following item(s) in the dataset:
 Radius of the PAW augmentation region
paw_radius
 This radius defines the region (around the atom) outside which all pseudo quantities are equal to the allelectron ones. It is equal to the maximum of all the cutoff and matching radii. Note that  for better lisibility  the
paw_radius
element should be provided in the header of the file.
End of the dataset
</paw_dataset>
How to use the datasets
Most likely, the radial functions will be needed on some other type of radial grid than the one used in the dataset. The idea is that one should read in the radial functions and then transform them to the radial grids used by the specific implementation. After the transformation, some sort of normalization may be necessary.
Plotting the radial functions
The first 1020 lines of the XMLdatasets, should be pretty much human readable, and should give an overview of what kind of dataset it is and how it was generated. The remaining part of the file contains numerical data for all the radial functions. To get an overview of these functions, you can extract that data with the pawxml.py program and then pass it on to your favorite plotting tool.
 Note: The
pawxml.py
program is very primitive and is only included in order to demonstrates how to parse XML using SAX from a Python program. Parsing XML from Fortran or C code with SAX should be similar.
Usage:
It works like this:
$ pawxml.py [options] dataset[.gz]
Options:
version

Show program's version number and exit. 
h, help

Show this help message and exit. 
x <name>, extract=<name>

Function to extract. 
s<channel>, state=<channel>

Select valence state. 
l, list

List valence states 
Examples:
[~]$ pawxml.py x pseudo_core_density N.LDA  xmgrace  [~]$ pawxml.py x ae_partial_wave s N2p N.LDA > N.ae.2p [~]$ pawxml.py x pseudo_partial_wave s N2p N.LDA > N.ps.2p [~]$ xmgrace N.??.2p
References
<references> ^{[1]} </ref> ^{[2]} ^{[3]} ^{[4]} ^{[5]}
 ↑ ^{1.0} ^{1.1} ^{1.2} ^{1.3} ^{1.4} ^{1.5} P. E. Blöchl, Projector AugmentedWave method, Phys. Rev. B 50, 1795319979 (1994)
 ↑ ^{2.0} ^{2.1} P. E. Blöchl, C. J. Forst and J. Schimpl, Projector AugmentedWave method: Ab initio molecular dynamics with full wave functions, Bulletin of Materials Science 26, 3341 (2003)
 ↑ ^{3.0} ^{3.1} N. A. W. Holzwarth, A. R. Tackett, and G. E. Matthews, A Projector Augmented Wave (PAW) code for electronics structure calculations: Part I atompaw for generating atomcentered functions, Computer Physics Communications 135, 329347 (2001)
 ↑ ^{4.0} ^{4.1} ^{4.2} ^{4.3} G. Kresse and D. Joubert, Form ultrasoft pseudopotentials to the projector augmentedwave method, Phys. Rev. B 59, 17581775 (1999)
 ↑ ^{5.0} ^{5.1} K. Laasonen, A. Pasquarello, R. Car, C. Lee and D. Vanderbilt, CarParrinello molecular dynamics with Vanderbilt ultrasoft pseudopotentials, Phys. Rev. B 47, 1014210153 (1993)