VTF format

Olaf Lenz edited this page Oct 19, 2016 · 6 revisions

The VTF trajectory/structure/coordinate format was designed for people using their own hand-written simulation codes and coarse-grained simulations that want to visualize their simulations using VMD. In VTF, VSF and VCF files, it is possible to specify all properties that are used by the VMD viewer.

The format is used by the coarse-grained simulation package ESPResSo.

An example VTF file can be found here.

Table of Contents

Basic file format

  • The basic unit of a file is a line.
  • A block consists of an arbitrary number of lines, up to a line starting a new block.
  • Files consist of structure blocks and timestep/coordinate blocks.
  • VSF (VTF Structure Format) files only contain a structure block.
  • VCF (VTF Coordinate Format) files only contain timestep/coordinate blocks.
  • VTF (VTF Trajectory Format) files start with a structure block and contain an arbitrary number of timestep blocks afterwards.
  • Lines ending with the character `\` are continuation lines, i.e. the line is concatenated with the next line to form a single line.
  • Comment lines starting with `#` and lines containing only whitespace characters are ignored.
  • Leading whitespace characters in a line are ignored.

Structure blocks

Structure blocks describe the structure of a simulated system, i.e. the characteristics of the atoms, the bonds, and the unitcell size. Structure blocks consist of Atom lines, Bond lines and Unitcell lines. The type of each line is identified by the first non-whitespace character.

Atom lines

Atom lines define atoms and their properties.


 # Specify 4 coarse-grained lipids with 7 beads each
 atom 0,7,14,21 name HEAD resname LIPID radius 1.1
 atom 1:2,8:13,15:20,22:27 name TAIL resname LIPID radius 1.0
 atom 0:6 resid 0 segid UPPER
 atom 7:13 resid 1 segid UPPER
 # in fact, 'a' is enough to identify an atom line
 a 14:20 resid 2 segid LOWER
 # or even no keyword at all
 21:27 resid 3 segid LOWER


[a[tom]] <aid-specifier>[, <aid-specifier>...] [<options>...]


  • n[ame] <char[16]>: atom name
  • t[ype] <char[16]>: atom type
  • resid <int>: residue id
  • res[name] <char[8]>: residue name
  • r[adius] <float>: VDW radius
  • s[egid] <char[8]>: segment id
  • c[hain] <char[2]>: chain id
  • charge|q <float>: charge
  • a[tomicnumber] <int>: atomic number
  • altloc <char[2]>: PDB alternative location
  • i[nsertion] <char[2]>: PDB insertion
  • o[ccupancy] <float>: occupancy
  • b[factor] <float>: b-factor
  • m[ass] <float>: mass


  • The line starts with an aid-specifier or the keyword a[tom].
  • An aid-specifier specifies, which atoms the line refers to:
    • default refers to the default atom that is used as a template for new atoms.
    • A single atom id specifies a single atom.
    • A range specifier <from>:<to> denotes a range of atoms.
    • Whenever an atom id is used that is greater than the greatest atom id so far, all atoms up to this new greatest id are made copies of the default atom.
  • The options can be used to specify the different properties of the atoms.
  • You can have more than a single atom line to define the properties of an atom. The final properties of an atom are a combination of the properties given on all atom lines.

Bond lines

Bond lines define bonds between atoms. They can occur in a structure block in the VTF format.


 # Specify a ring of 6 atoms
 bond 0::5,5:0


b[ond] <bond-specifier>[, <bond-specifier>...]


  • The line starts with the keyword b[ond].
  • A bond-specifier defines one or more bonds:
    • <from>:<to> defines a bond between atoms from and to
    • <from>::<to> defines, that the atoms between from and to are a chain with bonds between two adjacent atoms.

Unitcell lines

Unitcell lines define the size of the unitcell (or periodic boundary conditions) of the system.


 unitcell 10.0 10.0 10.0 90 90 90


p[bc]|u[nitcell] <a> <b> <c> [<alpha> <beta> <gamma>]


  • The line starts with one of the keywords u[nitcell] or p[bc].
  • a, b, and c define the dimensions of the unitcell in x,y and z directions.
  • alpha, beta and gamma define the angles (in degrees) of the unitcell as defined in the VMD user's guide.
  • If the angles are omitted, the unitcell is assumed to be rectangular (i.e. alpha=beta=gamma=90).

Timestep/coordinate blocks

Timestep/coordinate blocks describe the positions of the atoms in a simulated system, as well as the size of the unitcell in a given timestep in a simulation where the unitcell size changes. A timestep/coordinate block starts with a Timestep line. The following lines are either Unitcell lines (as in the structure block) or Coordinate definition lines in ordered or indexed format. If the unitcell data or the coordinates of some of the atoms are not specified in a timestep, they are taken from the previous timestep, if accessible.

Timestep lines

A timestep line defines the beginning of a new timestep block in the VTF format, and it defines the format of the coordinate definition lines in the block.


t[imestep]|c[oordinates] [i[ndexed]|o[rdered]]|i[ndexed]|o[rdered]


  • The line starts with one of the keywords t[imestep], c[oordinates], i[ndexed] or o[rdered].
  • The keyword o[rdered] specifies that the following coordinate definition lines are in ordered format.
  • The keyword i[ndexed] specifies that the following coordinate definition lines are in indexed format.
  • If no corresponding keyword is found, the following coordinate definition lines are assumed to be in ordered format.


  # several variants
  timestep indexed
  # very short
  t i

Coordinate definition lines

Coordinate definition lines define the coordinates of a single atom in the system.


  timestep indexed
  0 5.0 7.0 5.0

Syntax (ordered)

<x> <y> <z>

Syntax (indexed)

<aid> <x> <y> <z>


  • In ordered format, the lines are associated with ascending atom ids.
  • In indexed format, the coordinates x, y and z are associated to the atom id aid.
  • The first timestep in a multi-timestep file should be an ordered timestep, so that all atoms are defined.
  • The timestep in a single-timestep file should be an ordered timestep, so that all atoms are defined.
  • The rest of the line that does not specify the coordinates and aid will be ignored.
Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.