VTF trajectory/structure/coordinate format
From ESPResSo
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.
For those that prefer to learn by example, you can find the full example file below.
Contents |
[edit] 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.
[edit] 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. Each line is identified by the first non-whitespace character.
[edit] Atom lines
Atom lines define atoms and their properties.
[edit] Syntax
[a[tom]] aid-specifier[,aid-specifier...] [options...]
| Option | Description |
|---|---|
| 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 |
[edit] Description
- 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.
[edit] Example
# 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
[edit] Bond lines
Bond lines define bonds between atoms.
[edit] Syntax
b[ond] bond-specifier[,bond-specifier...]
[edit] Description
- 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.
[edit] Example
# Specify a ring of 6 atoms bond 0::5,5:0
[edit] Unitcell lines
Unitcell lines define the size of the unitcell (or periodic boundary conditions) of the system.
[edit] Syntax
p[bc]|u[nitcell] a b c [alpha beta gamma]
[edit] Description
- 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).
[edit] Example
unitcell 10.0 10.0 10.0 90 90 90
[edit] 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.
[edit] Timestep lines
A timestep line defines the beginning of a new timestep block, and it defines the format of the coordinate definition lines in the block.
[edit] Syntax
t[imestep]|c[oordinates] [i[ndexed]|o[rdered]]|i[ndexed]|o[rdered]
[edit] Description
- 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 assumend to be in ordered format.
[edit] Example
# several variants timestep coordinates timestep indexed ordered # very short t i
[edit] Coordinate definition lines
Coordinate definition lines define the coordinates of a single atom in the system.
[edit] Syntax (ordered)
x y z
[edit] Syntax (indexed)
aid x y z
[edit] Description
- In ordered format, the lines are associated with ascending atom ids.
- In indexed format, the coordinates x, y and z are associated with 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.
[edit] Example
timestep ordered 4.0 7.0 5.0 6.0 7.0 5.0 7.0 5.0 5.0 6.0 3.0 5.0 4.0 3.0 5.0 3.0 5.0 5.0
timestep indexed 0 5.0 7.0 5.0
[edit] Full example file
############################## # EXAMPLE VTF TRAJECTORY FILE ############################## # STRUCTURE BLOCK # define the default atom atom default radius 0.8 name H # define atoms 0, 2 and 4; atoms 1 and 3 will be filled with the default atom 0,2,4 radius 1.0 name N # define atoms 6 to 10 atom 6:10 radius 0.5 name O # make a cyclic ring of atoms 0 to 5 bond 0:5,0::5 # make a chain of atoms 6 to 10 bond 6::10 # TIMESTEP BLOCKS # start a new timestep (ordered by default) timestep # set the unitcell pbc 10.0 10.0 10.0 # now define the coordinates 4.0 7.0 5.0 6.0 7.0 5.0 7.0 5.0 5.0 6.0 3.0 5.0 4.0 3.0 5.0 3.0 5.0 5.0 5.0 5.0 1.0 5.0 5.0 3.0 5.0 5.0 5.0 5.0 5.0 7.0 5.0 5.0 9.0 # start another timestep timestep 6.0 7.0 5.0 7.0 5.0 5.0 6.0 3.0 5.0 4.0 3.0 5.0 3.0 5.0 5.0 4.0 7.0 5.0 5.0 5.0 1.5 5.0 5.0 3.5 5.0 5.0 5.5 5.0 5.0 7.5 5.0 5.0 9.5 # now start an indexed timestep timestep indexed pbc 11.0 11.0 11.0 6 5.0 5.0 1.0 7 5.0 5.0 3.0 8 5.0 5.0 5.0 9 5.0 5.0 7.0 10 5.0 5.0 9.0
