Home | About | Description | Documentation
| Download | News | Register

The
XSF Format Specification

Table of
Contents

Specification
of the XSF Format

Introduction
to XSF format

Comment
lines
Specification
of Molecular
Structure

Specification
of Periodic
Structures

Specification
of Forces

Specification
of Animated XSF
format

Animated
XSF for molecules

Animated
XSF for periodic structures

Fixed-cell
animated XSF

Variable-cell
animated XSF
Specification
of 2D and 3D
scalar-fields

General
vs. Periodic grids

Datagrids

Bandgrids
(visualization of Fermi
surfaces)

Specification of the XSF Format

Introduction to XSF format
The XSF
format is internal XCrySDen structure format. XSF
stands for XCrySDen
Structure File. It is used to describe (i) molecular and
crystal structure, (ii) forces acting on constituent atoms, and
(iii) scalar fields (for example: charge density, electrostatic
potential). The main attributes of XSF format are:

all records are in free format

the XSF formatted file is composed from various sections

each sections begins with the keyword

there are two types of keywords: (i) single
keywords, and (ii) sandwich keywords, which are defined
as:

single keyword: section begins with a single
keyword and ends without an end-keyword

sandwich keyword: section begins with a
begin-keyword (i.e. BEGIN_keyword) and ends with
an end-keyword (i.e. END_keyword), where
keyword is one among keywords.

all coordinates are in ANGSTROMS units

all forces are in Hartree/ANGSTROM units

the comment-lines start with the "#" character (see below)

Comment lines
The comment-lines were
introduced to the XSF file starting from XCrySDen version 1.4. The
comment-lines start with the "#" character; comments are
allowed only between sections and not within a given section. Here
are two examples (correct and incorrect).

Correct example (comments are bewteen the sections):

# this is a specification
# of ZnS crystal structure

CRYSTAL

# these are primitive lattice vectors (in Angstroms)

PRIMVEC
2.7100000000 2.7100000000 0.0000000000
2.7100000000 0.0000000000 2.7100000000
0.0000000000 2.7100000000 2.7100000000

# these are convetional lattice vectors (in Angstroms)

CONVVEC
5.4200000000 0.0000000000 0.0000000000
0.0000000000 5.4200000000 0.0000000000
0.0000000000 0.0000000000 5.4200000000

# these are atomic coordinates in a primitive unit cell
# (in Angstroms)

PRIMCOORD
2 1
16 0.0000000000 0.0000000000 0.0000000000
30 1.3550000000 -1.3550000000 -1.3550000000

Incorrect
example (comment is within the section):

ATOMS
6 2.325243 -0.115261 0.031711
1 2.344577 -0.363301 1.077589
#
# this is a comment on the wrong place
#
6 0.007719 -0.041269 0.244204
9 0.064656 1.154700 0.824420
9 -0.042641 -0.911850 1.255074
8 -1.071578 -0.152842 -0.539134

Specification of Molecular
Structure
For MOLECULES the XSF format is very simple. The
first line begins with the ATOMS keyword and then one
specifies the structural data for all atoms. An entry for an atom
looks like:
AtNum X Y Z

where AtNum stands for atomic number (or
symbol), while X Y Z are Cartesian coordinates in
ANGSTROMS units. Here is one example:

ATOMS
6 2.325243 -0.115261 0.031711
1 2.344577 -0.363301 1.077589
9 3.131708 -0.909527 -0.638930
9 2.736189 1.130568 -0.134093
8 1.079338 -0.265162 -0.526351
6 0.007719 -0.041269 0.244204
9 0.064656 1.154700 0.824420
9 -0.042641 -0.911850 1.255074
8 -1.071578 -0.152842 -0.539134
6 -2.310374 0.036537 0.022189
1 -2.267004 0.230694 1.077874
9 -2.890949 1.048938 -0.593940
9 -3.029540 -1.046542 -0.203665

Specification of Periodic
Structures
The XSF format allows to specify structures of
different periodicity. The keywords MOLECULE,
POLYMER, SLAB, and CRYSTAL
designate the 0-, 1-, 2-, and 3-dimensional structures (i.e.
periodic dimensions are meant here). For crystal structures the
file begin with CRYSTAL keyword. Then one needs to
specify the lattice vectors and the atoms belonging to the unit
cell. XCrySDen accepts
two different setting of the unit cell. These are usually called
the primitive and the conventional unit cell. The corresponding
keywords are PRIMVEC for primitive lattice vectors
and PRIMCOORD for atoms belonging to the primitive
unit cell. The CONVVEC and CONVCOORD
have the analogous meaning for the conventional unit cell.
Warning: in XSF file the two settings of the unit cell are
supposed to have the same origin. If you want to specify some
crystal structure with two settings of the unit cell, that have
different origins you will have to create two XSF files. In
practice only PRIMVEC, PRIMCOORD and
CONVVEC need to be specified, and then "conventional
coordinates" (CONVCOORD) are generated by XCrySDen itself, hence it is
never needed to specify the CONVCOORD section
!!! Here is an example of ZnS crystal structure:

CRYSTAL see (1)
PRIMVEC
0.0000000 2.7100000 2.7100000 see (2)
2.7100000 0.0000000 2.7100000
2.7100000 2.7100000 0.0000000
CONVVEC
5.4200000 0.0000000 0.0000000 see (3)
0.0000000 5.4200000 0.0000000
0.0000000 0.0000000 5.4200000
PRIMCOORD
2 1 see (4)
16 0.0000000 0.0000000 0.0000000 see (5)
30 1.3550000 -1.3550000 -1.3550000

Legend:

(1)

this keyword specify the structure is
crystal

(2)

specification of PRIMVEC (in
ANGSTROMS)
like:
ax,
ay, az    (first lattice
vector)
bx,
by, bz    (second lattice
vector)
cx,
cy, cz    (third lattice
vector)

(3)

specification of CONVVEC
(see (2))

(4)

First number stands for number of atoms
in the primitive cell (2 in this case). The second number is
always 1 for PRIMCOORD
coordinates.

(5)

Specification of atoms in the primitive
cell (the same as for ATOMS
section).

Specification of Forces
All that is
needed to specify the forces acting on atoms is to supplement the
appropriate coordinate section (ATOMS or
PRIMCOORD). Now an entry for an atom would look like:

AtNum X Y Z Fx Fy Fz

where Fx Fy Fz stands for force components in
X, Y and Z direction, respectively. The force components are
expressed in Cartesian coordinate system in Hartree/ANGSTROM unit.
Here is an example of water molecule:

ATOMS
8 0.00000 0.00000 0.00000 -.05164 .00000 -.03999
1 0.00000 0.00000 1.00000 .01769 .00000 .03049
1 0.96814 0.00000 -0.25038 .03395 .00000 .00949

And here is an
example for the periodic structure structure:

SLAB
PRIMVEC
5.8859828533 0.0000000000 0.0000000000
0.0000000000 5.8859828533 0.0000000000
0.0000000000 0.0000000000 1.0000000000
PRIMCOORD 1
11 1
6 3.674759 2.942992 -3.493103 -0.021668 0.000000 -0.057324
1 4.121990 3.816734 -4.007689 -0.000478 0.001204 0.006657
1 4.121990 2.069250 -4.007689 -0.000478 -0.001204 0.006657
6 2.211226 2.942992 -3.493103 0.021668 0.000000 -0.057324
1 1.763995 3.816734 -4.007689 0.000478 0.001204 0.006657
1 1.763995 2.069250 -4.007689 0.000478 -0.001204 0.006657
8 0.000000 0.000000 -2.719012 0.000000 0.000000 -0.050242
47 4.448147 4.449892 -1.919011 -0.022812 -0.029123 0.007553
47 4.448147 1.436093 -1.919011 -0.022812 0.029123 0.007553
47 1.437838 4.449892 -1.919011 0.022812 -0.029123 0.007553
47 1.437838 1.436093 -1.919011 0.022812 0.029123 0.007553

Specification of Animated XSF
format
It is possible to specify several snapshots of a
structure in the XSF format. For example: the file can contain the
data for all structures that were created during an optimization
run or molecular-dynamics run. These structures can be displayed
as animation by XCrySDen.
The main attributes of the animated XSF format are:

the AXSF file begins with the ANIMSTEPS
nstep keyword, where nstep
stands for number of animation steps.

number of atoms for all steps must be the same
!!!

in fixed-cell animated XSF for crystal structures the unit
cell for all steps is taken to be the same

in variable-cell animated XSF for crystal structures the
unit cell is specified for each animation step

the ATOMS and PRIMCOORD keywords
are prefixed by an integer number which is the sequential index
of a given snapshot. Therefore the syntax is ATOMS
istep and PRIMCOORD istep.

for variable-cell crystal structure the PRIMVEC
and CONVVEC keywords are prefixed with sequential
index.

Animated XSF for molecules
Here is an
example of AXSF file. It shows different structures during an
optimization of water molecule. Note the index prefixes after
ATOMS keywords.

ANIMSTEPS 4
ATOMS 1
8 0.0000 0.0000 0.0000 -0.0516 0.0000 -0.0399
1 0.0000 0.0000 1.0000 0.0176 0.0000 0.0304
1 0.9681 0.0000 -0.2503 0.0339 0.0000 0.0094
ATOMS 2
8 -0.1480 0.0000 -0.1146 0.0020 0.0000 0.0015
1 -0.0468 0.0000 0.9134 -0.0069 0.0000 0.0069
1 0.8726 0.0000 -0.2740 0.0049 0.0000 -0.0084
ATOMS 3
8 -0.1032 0.0000 -0.0799 0.0013 0.0000 0.0010
1 -0.0319 0.0000 0.9591 0.0011 0.0000 -0.0028
1 0.9205 0.0000 -0.2710 -0.0025 0.0000 0.0018
ATOMS 4
8 -0.1102 0.0000 -0.0853 0.0001 0.0000 0.0000
1 -0.0345 0.0000 0.9503 -0.0000 0.0000 -0.0000
1 0.9114 0.0000 -0.2714 -0.0000 0.0000 -0.0000

Animated XSF for periodic structures

Fixed-cell animated XSF
Here is an
example of animated XSF for the ZnS crystal structure with the
fixed unit-cell. Note the index prefixes after
PRIMCOORD keywords.

ANIMSTEPS 2
CRYSTAL
PRIMVEC
0.0000000 2.7100000 2.7100000
2.7100000 0.0000000 2.7100000
2.7100000 2.7100000 0.0000000
PRIMCOORD 1
2 1
16 0.0000000 0.0000000 0.0000000
30 1.3550000 -1.3550000 -1.3550000
PRIMCOORD 2
2 1
16 0.0000000 0.0000000 0.0000000
30 1.2550000 -1.2550000 -1.2550000

Variable-cell animated XSF
Here is
an example of animated XSF for the ZnS crystal structure with the
variable unit-cell. Note the index prefixes after
PRIMVEC, CONVVEC, and
PRIMCOORD keywords.

ANIMSTEPS 2
CRYSTAL
PRIMVEC 1
2.7100000 2.7100000 0.00000000
2.7100000 0.0000000 2.71000000
0.0000000 2.7100000 2.71000000
CONVVEC 1
5.4200000 0.0000000 0.00000000
0.0000000 5.4200000 0.00000000
0.0000000 0.0000000 5.42000000
PRIMCOORD 1
2 1
16 0.0000000 0.0000000 0.00000000
30 1.3550000 -1.3550000 -1.35500000
PRIMVEC 2
2.9810000 2.9810000 0.00000000
2.9810000 0.0000000 2.98100000
0.0000000 2.9810000 2.98100000
CONVVEC 2
5.9620000 0.0000000 0.00000000
0.0000000 5.9620000 0.00000000
0.0000000 0.0000000 5.96200000
PRIMCOORD 2
2 1
16 0.0000000 0.0000000 0.00000000
30 1.5905000 -1.5905000 -1.59050000

Specification of 2D and 3D
scalar-fields
It is possible to specify one or several
scalar fields (both 2D and 3D) as an uniform mesh of values
in the XSF formatted file. The mesh can be non-orthogonal.
This scalar field meshes are called datagrids.

General vs. Periodic grids
Datagrids
in XCrySDen are general
grids and not periodic one!!! What is meant by this will be
explained bellow. A general grid is a uniform grid that is spanned
inside some box, which is either non-orthogonal or orthogonal. For
a molecule such a box would be a bounding box, while for crystal
such a box would be a unit cell. However in a grid that span a
whole unit-cell some border points would be redundant due to
translational symmetry. Grids that omit these redundant points are
called periodic (by this convention a FFT (fast-Fourier transform)
mesh would be a periodic mesh). The general vs. periodic grid
concept is shown graphically here:

Note:
datagrids in XCrySDen are
general grids !!!

Datagrids
The datagrid section is
structured and organized in blocks. The grids inside a block can
be manipulated among themselves by XCrySDen program. The main
attributes of XSF datagrids are:

(1)

the top datagrid section is called
BLOCK_DATAGRID and is sandwiched between
BEGIN_BLOCK_DATAGRID_xD and
END_BLOCK_DATAGRID_xD keywords, where
x stands for the dimensionality of the grid.
Currently 2D and 3D scalar grids are supported.

(2)

there can be an arbitrary number of
BLOCK_DATAGRID sections.

(3)

there can be an arbitrary number of
datagrids inside one BLOCK_DATAGRID section. All datagrids
belonging to the same BLOCK_DATAGRID must have the
dimensionality as defined by
BEGIN_BLOCK_DATAGRID_xD keyword. These
datagrids must also share the following properties: (i) they
should span the same space (origin and the spanning vectors
must be the same), and (ii) they should have the same number
of data-points. Each datagrid in a BLOCK_DATAGRID is
sandwiched inside BEGIN_DATAGRID_xD_identifier
and END_DATAGRID_xD keywords, where
x stands for dimensionality of the grid and the
identifier is used as an identifier of the
datagrid.

(4)

after the
BEGIN_BLOCK_DATAGRID_xD keyword and before the
first DATAGRID_xD_identifier keyword is a
comment, which is used as an identifier for the
BLOCK_DATAGRID. It must be a single
word!!!

(5)

the values inside a datagrid are
specified in column-major (i.e. FORTRAN) order. This means
that values are written as:

C-syntax:
for (k=0; k<nz; k++)
for (j=0; j<ny; j++)
for (i=0; i<nx; i++)
printf("%f",value[i][j][k]);

FORTRAN syntax:
write(*,*)
$ (((value(ix,iy,iz),ix=1,nx),iy=1,ny),iz=1,nz)

Above
specifications may sound very fuzzy, hence let us clarify this by
looking at a very simple example. The description
of all records follows after the example. Also take a look at schematic
presentation of the structure of datagrids of below example.

l.01
l.02
l.03
l.04
l.05
l.06
l.07
l.08
l.09
l.10
l.11
l.12
l.13
l.14
l.15
l.16
l.17
l.18
l.19
l.20
l.21
l.22
l.23
l.24
l.25
l.26
l.27
l.28
l.29
l.30
l.31
l.32
l.33
l.34
l.35
l.36
l.37
l.38
l.39
l.40
l.41
l.42
l.43
l.44
l.45
l.46
l.47
l.48
l.49
l.50
l.51
l.52
l.53
l.54
l.55
l.56
l.57
l.58
l.59
l.60
l.61
l.62
l.63
l.64
l.65

BEGIN_BLOCK_DATAGRID_2D
my_first_example_of_2D_datagrid
BEGIN_DATAGRID_2D_this_is_2Dgrid#1
5 5
0.0 0.0 0.0
1.0 0.0 0.0
0.0 1.0 0.0
0.000 1.000 2.000 5.196 8.000
1.000 1.414 2.236 5.292 8.062
2.000 2.236 2.828 5.568 8.246
3.000 3.162 3.606 6.000 8.544
4.000 4.123 4.472 6.557 8.944
END_DATAGRID_2D
BEGIN_DATAGRID_2D_this_is_2Dgrid#2
5 5
0.0 0.0 0.0
1.0 0.0 0.0
0.0 1.0 0.0
4.000 4.123 4.472 6.557 8.944
3.000 3.162 3.606 6.000 8.544
2.000 2.236 2.828 5.568 8.246
1.000 1.414 2.236 5.292 8.062
0.000 1.000 2.000 5.196 8.000
END_DATAGRID_2D
END_BLOCK_DATAGRID_2D

BEGIN_BLOCK_DATAGRID_3D
my_first_example_of_3D_datagrid
BEGIN_DATAGRID_3D_this_is_3Dgrid#1
5 5 5
0.0 0.0 0.0
1.0 0.0 0.0
0.0 1.0 0.0
0.0 0.0 1.0
0.000 1.000 2.000 5.196 8.000
1.000 1.414 2.236 5.292 8.062
2.000 2.236 2.828 5.568 8.246
3.000 3.162 3.606 6.000 8.544
4.000 4.123 4.472 6.557 8.944

1.000 1.414 2.236 5.292 8.062
1.414 1.732 2.449 5.385 8.124
2.236 2.449 3.000 5.657 8.307
3.162 3.317 3.742 6.083 8.602
4.123 4.243 4.583 6.633 9.000

2.000 2.236 2.828 5.568 8.246
2.236 2.449 3.000 5.657 8.307
2.828 3.000 3.464 5.916 8.485
3.606 3.742 4.123 6.325 8.775
4.472 4.583 4.899 6.856 9.165

3.000 3.162 3.606 6.000 8.544
3.162 3.317 3.742 6.083 8.602
3.606 3.742 4.123 6.325 8.775
4.243 4.359 4.690 6.708 9.055
5.000 5.099 5.385 7.211 9.434

4.000 4.123 4.472 6.557 8.944
4.123 4.243 4.583 6.633 9.000
4.472 4.583 4.899 6.856 9.165
5.000 5.099 5.385 7.211 9.434
5.657 5.745 6.000 7.681 9.798
END_DATAGRID_3D
END_BLOCK_DATAGRID_3D

Legend:

l.01

beginning of 2D block of
datagrids

l.02

one word comment - used as an identifier
for this block

l.03

beginning of the first 2D datagrid in a
block

l.04

number of data-points in each direction
(i.e. nx ny for 2D grids)

l.05

origin of the datagrid

l.06

first spanning vector of the
datagrid

l.07

second spanning vector

l.08-12

5x5 datagrid values in column-major
mode

l.13

end of the first 2D datagrid in a
block

l.14-24

these lines specify second 2D datagrid in
a block in totally analogous manner as the first 2D
datagrid.

l.25

end of 2D block of
datagrids

l.27

beginning of 3D block of
datagrids

l.28

one word comment - used as an identifier
for this block

l.29

beginning of the first 3D datagrid in a
block

l.30

number of data-points in each direction
(i.e. nx ny nz for 3D grids)

l.31

origin of the datagrid

l.32

first spanning vector of the
datagrid

l.33

second spanning vector

l.34

third spanning vector

l.35-63

5x5x5 datagrid values in column-major
mode

l.64

end of the first 3D datagrid in a
block

l.65

end of 3D block of
datagrids

Here is a scheme of
the structure of datagrids of above example as displayed by XCrySDen program.

Bandgrids (visualization of Fermi
surfaces)
Bandgrids are variation on a theme of
datagrids. They were introduced for the visualization of Fermi
surfaces and yields a simplified format of datagrids.
Please notice that despite their purpose they are still general
grids and not periodic ones. The bandgrid for the
visualization of Fermi surface should be defined as:

Please
notice that the bandgrid span the reciprocal unit cell, not the
Brillouin zone !!! Points are later translated back to Brillouin
zone by XCrySDen and
Fermi surface is rendered inside the Brillouin zone.
Warning: so far XCrySDen uses
bandgrids solely for the visualization of Fermi surfaces
(the coresponding files are called BXSF, standing for Band-XSF).
If you want to render some other property as contours/isosurfaces
you must specify the scalar fields as datagrids. This is
because the Fermi surfaces needs some special processing and
therefore bandgrids are automatically processed. The main
attributes of bandgrids are:

(1)

the structure of bandgrids is
similar to datagrids

(2)

there can only be one BLOCK_BANDGRID
section

(3)

there can only be one BANDGRID in
BLOCK_BANDGRID

(4)

there can be an arbitrary number of
bands inside BANDGRID section, where BAND is
...

(5)

so far only 3D bandgrids are
supported

BEWARE:

the values inside a bandgrid are
specified in row-major
(i.e. C) order. This means that values are written as:

C-syntax:
for (i=0; i<nx; i++)
for (j=0; j<ny; j++)
for (k=0; k<nz; k++)
printf("%f",value[i][j][k]);

FORTRAN syntax:
write(*,*)
$ (((value(ix,iy,iz),iz=1,nz),iy=1,ny),ix=1,nx)

Here is a
bandgrid example. The description of the records is below
the example.

l.01
l.02
l.03
l.04
l.05
l.06
l.07
l.08
l.09
l.10
l.11
l.12
l.13
l.14
l.15
l.16
l.17
l.18
l.19
l.20
l.21
l.22
l.23
l.24
l.25
l.26
l.27
l.28
l.29
l.30
l.31
l.32
l.33
l.34
l.35
l.36
l.37
l.38
l.39
l.40
l.41
l.42
l.43
l.44
l.45
l.46
l.47
l.48
l.49
l.50
l.51
l.52
l.53
l.54
l.55
l.56
l.57
l.58
l.59
l.60
l.61
l.62
l.63

BEGIN_INFO
#
# this is a sample Band-XCRYSDEN-Structure-File
# aimed for Visualization of Fermi Surface
#
# Case: just an example
#
# Launch as: xcrysden --bxsf example.bxsf
#
Fermi Energy: 0.83511
END_INFO

BEGIN_BLOCK_BANDGRID_3D
here_we_have_some_examples
BEGIN_BANDGRID_3D_simple_example
2
4 4 4
0.0 0.0 0.0
1.0 0.0 0.0
0.0 1.0 0.0
0.0 0.0 1.0
BAND: 3
0.000 0.192 0.385 0.577
0.192 0.272 0.430 0.609
0.385 0.430 0.544 0.694
0.577 0.609 0.694 0.816

0.192 0.272 0.430 0.609
0.272 0.333 0.471 0.638
0.430 0.471 0.577 0.720
0.609 0.638 0.720 0.839

0.385 0.430 0.544 0.694
0.430 0.471 0.577 0.720
0.544 0.577 0.667 0.793
0.694 0.720 0.793 0.903

0.577 0.609 0.694 0.816
0.609 0.638 0.720 0.839
0.694 0.720 0.793 0.903
0.816 0.839 0.903 1.000
BAND: 4
1.000 0.942 0.885 0.827
0.942 0.918 0.871 0.817
0.885 0.871 0.837 0.792
0.827 0.817 0.792 0.755

0.942 0.918 0.871 0.817
0.918 0.900 0.859 0.809
0.871 0.859 0.827 0.784
0.817 0.809 0.784 0.748

0.885 0.871 0.837 0.792
0.871 0.859 0.827 0.784
0.837 0.827 0.800 0.762
0.792 0.784 0.762 0.729

0.827 0.817 0.792 0.755
0.817 0.809 0.784 0.748
0.792 0.784 0.762 0.729
0.755 0.748 0.729 0.700
END_BANDGRID_3D
END_BLOCK_BANDGRID_3D

Legend:

l.01

beginning of INFO
section

l.02-09

a hash "#" character stands for
comment

l.10

a "Fermi Energy:" string is
a marker for reading the value of Fermi energy

l.11

end of INFO section

l.13

beginning of 3D block of
bandgrids

l.14

one word comment - used as an identifier
for this block

l.15

beginning of the 3D bandgrid

l.16

number of bands in the
bandgrid

l.17

number of data-points in each direction
(i.e. nx ny nz for 3D grids)

l.18

origin of the bandgrid
Warning:
origin should be (0,0,0) (i.e. Gamma point)

l.19

first spanning vector of the bandgrid
(i.e. first reciprocal lattice vector)

l.20

second spanning vector

l.21

third spanning vector

l.22

beginning of the BAND with label
3

l.23-41

4x4x4 values in row-major
mode

l.42

beginning of the BAND with label
4

l.43-61

4x4x4 values in row-major
mode

l.62

end of the bandgrid

l.63

end of 3D bandgrid
block

Home | About | Description | Documentation | Download
| News |
Register

Webmaster: Tone
Kokalj
This document was last modified on Fri Dec 5 17:06:30 CET
2008