XSF file reader

For loading atomic structures, trajectories, and volumetric data stored in the XSF (XCrySDen Structure File) format, the native text format of the XCrySDen crystalline and molecular structure visualization program. XSF files are also written by various ab initio codes and their post-processing tools, e.g. Quantum ESPRESSO and Wannier90, to export charge densities, wave functions, and other scalar fields together with the atomic structure. OVITO can directly load gzipped XSF files (“.gz” suffix) and zstd compressed files (“.zst” suffix).

OVITO recognizes files of this format automatically based on their contents, i.e. if one of the keywords ATOMS, PRIMCOORD, CONVCOORD, or BEGIN_BLOCK_DATAGRID appears within the first 40 lines of the file. The file name extension (“.xsf” or “.axsf”) plays no role.

Imported data

The file reader parses the following sections of an XSF file:

Structure type

The keywords MOLECULE, POLYMER, SLAB, and CRYSTAL determine the dimensionality of the periodic system and are translated into the periodic boundary condition flags of the simulation cell: none, x, x and y, or all three directions, respectively. If none of these keywords is present, the cell is assumed to be periodic in all three directions.

Unit cell

The three lattice vectors of the primitive cell listed under PRIMVEC (in Angstroms) become the cell vectors of the simulation cell, with the cell origin at the coordinate origin. The conventional cell vectors (CONVVEC) are ignored.

Atoms

Atomic coordinates are read either from a PRIMCOORD section (periodic structures; the first line specifies the number of atoms) or from an ATOMS section (isolated molecules; the list of atoms extends until the first line that does not have the format of an atom record). The file reader creates the following per-atom properties:

  • Position — the Cartesian coordinates (in Angstroms).

  • Particle Type — the chemical element, which may be specified in the file either by its symbol (e.g. Si) or by its atomic number (e.g. 14). Atomic numbers are translated into element symbols, and OVITO assigns the standard CPK color and display radius of the element. Type names that do not correspond to a chemical element (e.g. the dummy atom symbol X used by XCrySDen) are imported as they are.

  • Force — the force vector acting on the atom (in Hartree/Angstrom), which XSF files may optionally store in three additional columns following the coordinates. This property is created only if the file contains the extra columns.

Files that describe a molecule using the ATOMS keyword contain no unit cell, and OVITO imports the atoms without a simulation cell unless the file also contains a data grid or the Generate bounding box if needed option is enabled (see below).

Trajectories

Animated XSF files (typically with “.axsf” suffix) begin with the ANIMSTEPS keyword, which specifies the number of animation frames. The atomic coordinates of each frame are given in a numbered section (PRIMCOORD 1, PRIMCOORD 2, … or ATOMS 1, ATOMS 2, …), which OVITO displays as a sequence of frames in the animation timeline. The number of atoms may vary from frame to frame. Both fixed-cell animations (a single PRIMVEC section) and variable-cell animations (numbered PRIMVEC 1, PRIMVEC 2, … sections) are supported.

Volumetric data

Three-dimensional data grids enclosed in a BEGIN_BLOCK_DATAGRID_3D … END_BLOCK_DATAGRID_3D block are imported as a voxel grid object. The identifier line following the block keyword serves as the identifier of the voxel grid (or imported if the line is empty). Each BEGIN_DATAGRID_3D_<name> section within the block becomes a scalar field property named <name> of the voxel grid, i.e. several data grids listed in the same block are imported as separate field properties of one and the same voxel grid. The grid dimensions, the origin, and the three spanning vectors specified in the file define the shape of the voxel grid and its spatial domain, which may differ from the unit cell of the atomic structure. The field values are interpreted by OVITO as being located at the grid line intersections (point data, see VoxelGrid.grid_type). The keyword variants BEGIN_BLOCK_DATAGRID3D, BLOCK_DATAGRID_3D, and DATAGRID_3D_<name> found in files written by some older programs are accepted as well.

If the file contains no PRIMVEC section, e.g. a molecule with a data grid, the origin and spanning vectors of the data grid are also used as the simulation cell. In any case, the periodicity of the grid domain follows the structure type of the atomic system (MOLECULE, SLAB, etc.; periodic in all directions if no structure type keyword is present).

The imported voxel grid is not visualized directly by default, i.e. its visual element is initially turned off. You can turn it on, or insert the Create isosurface modifier into the pipeline to visualize the field as an isosurface.

Vector fields

XCrySDen represents vector fields in an XSF file by dummy atoms with the symbol X, which are placed at the sampling points and carry the field vectors in the force columns. OVITO imports such records as regular particles of type X with the Force property, which you can visualize as arrows using the Vectors visual element.

Limitations

  • Only the primitive cell description is used. The conventional cell (CONVVEC) and the atomic coordinates listed in a CONVCOORD section are ignored.

  • The legacy DIM-GROUP header is ignored. Files using it instead of the CRYSTAL/SLAB/POLYMER/MOLECULE keywords are treated as 3d-periodic systems.

  • Two-dimensional data grids (BEGIN_BLOCK_DATAGRID_2D) and band grids (BEGIN_BLOCK_BANDGRID_3D) are not supported and skipped.

  • All data grids within the same BEGIN_BLOCK_DATAGRID_3D block must have identical dimensions. If a data grid with different dimensions is encountered, the previously loaded field properties of the voxel grid are discarded.

  • According to the XSF specification, the data values of a grid cover the entire spanning volume including the points on both boundaries, i.e. for periodic grids the first and last data points along each direction represent the same location. OVITO does not eliminate these duplicate boundary points. In periodic directions, the n values are distributed over the spanning vector with a uniform spacing of \(L/n\) instead of \(L/(n-1)\), which leads to a slight compression of the grid by a factor \((n-1)/n\). For fine grids this discrepancy is negligible.

  • All coordinates, cell vectors, and grid vectors are assumed to be in Angstrom units, as prescribed by the format. No unit conversion is performed.

  • The XSF format does not store bonds. Bonds can be generated after import using the Create bonds modifier.

Options

Generate bounding box if needed

If this option is enabled and the XSF file specifies neither a unit cell (PRIMVEC) nor a data grid, OVITO will generate an axis-aligned bounding box enclosing all atoms. This bounding box has open boundary conditions and serves as an approximate simulation cell.

Center simulation cell on coordinate origin

If enabled, OVITO shifts the simulation cell, all atom coordinates, and the domains of the data grids so that the geometric center of the simulation cell coincides with the coordinate origin. Otherwise, the origin of the unit cell is placed at the coordinate origin.

Python parameters

The file reader accepts the following optional keyword parameters in a call to the import_file() or load() Python functions.

import_file(location, bounding_box=False, centering=False)
Parameters:

  • bounding_box (bool) – Generate an ad-hoc simulation cell as a bounding box around the imported atoms when the file contains no unit cell and no data grid.

  • centering (bool) – Translate atom coordinates, simulation cell, and data grids to center the cell at the coordinate origin.