The .vesta file format¶
Herein I have manually reverse-engineered the key features of VESTA’s file format. The specification here is UNOFFICIAL, likely INCOMPLETE, and may contain INACCURACIES. Use with caution. Contributions welcome.
VESTA is a plain-text file. The amount of whitespace between entries on the same line does not seem to matter, neither does the number of decimal places in floating-point values.
The file has sections marked in all-caps, followed by a series of space- and newline-separated values.
#VESTA_FORMAT_VERSION¶
Metadata tag: version of the VESTA file format. The files I’m working with are in version 3.5.4.
A blank line follows it.
e.g.
#VESTA_FORMAT_VERSION 3.5.4
CRYSTAL¶
Superheader for each crystal Phase (Edit Data > Phases).
No data is associated with this field. However, it can appear multiple times. Following CRYSTAL are the sections from TITLE through to PLN2D inclusive, which contain the data specific to each crystal phase. (This means those sections are not unique.) Additional phases begin with another CRYSTAL header.
Has a blank line before and after it.
CRYSTAL
TITLE¶
Name/title of the structure.
One-line string. Defaults to “New structure”. Has a blank line after it.
e.g.
TITLE
New structure
IMPORT_DENSITY¶
Optional section.
Where to import volumetric density data from.
Has a flag 1
after the title (units??).
Each line is a file path (2nd item, string) and how to add it to the existing data (signed float, 1st item).
Has an empty line after it.
e.g.
IMPORT_DENSITY 1
+1.000000 CHGCAR
GROUP¶
Space group; the symmetry group imposed on the crystal.
e.g.
GROUP
1 1 P 1
SYMOP¶
Symmetry operations associated with GROUP.
e.g.
SYMOP
0.000000 0.000000 0.000000 1 0 0 0 1 0 0 0 1 1
-1.0 -1.0 -1.0 0 0 0 0 0 0 0 0 0
TRANM¶
e.g.
TRANM 0
0.000000 0.000000 0.000000 1 0 0 0 1 0 0 0 1
LTRANSL¶
Translation of this phase with respect to another.
Edit Data > Phase > Positioning
1st row: Reference phase (0-indexed). The number in “Place (x,y,z) of this layer at (x,y,z) of layer…” minus 1. If
-1
, is the global coordinate system.2nd row: x,y,z of this layer; x,y,z of reference layer.
e.g.
LTRANSL
-1
0.000000 0.000000 0.000000 0.000000 0.000000 0.000000
LORIENT¶
e.g.
LORIENT
-1 0 0 0 0
1.000000 0.000000 0.000000 1.000000 0.000000 0.000000
0.000000 0.000000 1.000000 0.000000 0.000000 1.000000
LMATRIX¶
Transformation matrix of this phase’s coordinate system.
5th row: 3 floats, translation. Is the (x,y,z) of the global coordinates minus the (x,y,z) of this phase, as specified in
LSTRANSL
. Actually, that’s only true in orthorhombic coordinates. Reality is actually rather complicated.
e.g.
LMATRIX
1.000000 0.000000 0.000000 0.000000
0.000000 1.000000 0.000000 0.000000
0.000000 0.000000 1.000000 0.000000
0.000000 0.000000 0.000000 1.000000
0.000000 0.000000 0.000000
CELLP¶
Unit cell lattice parameters. This data appears in Edit Data > Unit Cell > Lattice parameters.
Two lines of 6 floats each. The first line is a, b, c, alpha, beta, gamma. The second line is the s.u.: entries.
e.g.
CELLP
2.530000 2.530000 2.530000 60.000000 60.000000 60.000000
0.000000 0.000000 0.000000 0.000000 0.000000 0.000000
STRUC¶
Structure parameters.
Editable via Edit > Edit Data > Structure Parameters.
Has an entry for each (symmetrically-distinct) atom. Each atom gets two lines.
Row 1, item 1: No. / index (integer). Increments from 1. Not manually set.
Row 1, item 2: Elemental symbol (string)
Row 1, item 3: Site label (string)
Row 1, item 4: Occupation (default
1.0000
).Row 1, items 5-7: x,y,z coordinates (fractional)
Row 1, item 8: Wyckoff position/site? (default
1a
)Row 1, item 9: ? (default
1
)Row 2, items 1-3 (beneath row 1 items 5-7): x,y,z standard uncertainties (s.u.)
Row 2, item 4 (beneath row 1 item 8): Charge (default
0.00
)
Block ends with seven 0
’s.
e.g.
STRUC
1 Cu Cu 1.0000 0.000000 0.000000 0.000000 1a 1
0.000000 0.000000 0.000000 0.00
0 0 0 0 0 0 0
THERI¶
Isotropic U/B in Structure Parameters. (Isotropic thermal?)
In-line with the header is an integer flag defining whether we are using units of U or B.
0
if B, 1
if U. Default 1
.
One row for each site in STRUC.
Item 1: Site number/index.
Item 2: Site label.
Item 3: U or B value (float).
Block ends with three 0
’s.
N.B. if THERM is non-zero, it changes the value here.
e.g.
THERI 1
1 Cu 0.050000
0 0 0
THERT¶
Optional section.
Anisotropic thermal type.
Appears when Structure Parameters > Anisotropic is not None.
Single integer flag. 0
if units of U, 1
if units of beta.
e.g.
THERT 0
THERM¶
Optional section.
Appears when Structure Parameters > Anisotropic is not None.
One row for each site.
Item 1: Site index.
Item 2: Site label.
Items 3-8: U11, U22, U33, U12, U13, U23.
Ends in eight 0
’s.
Overwrites THERI if non-zero.
e.g.
THERM
1 Cu1 0.11000 0.22000 0.33000 0.12000 0.13000 0.23000
2 Cu 0.00000 0.00000 0.00000 0.00000 0.00000 0.00000
0 0 0 0 0 0 0 0
SHAPE¶
e.g.
SHAPE
0 0 0 0 0.000000 0 192 192 192 192
BOUND¶
Boundary.
1st item: x min
2nd item: x max
3rd item: y min
4th item: y max
5th item: z min
6th item: z max
Block ends with five 0
’s.
e.g.
BOUND
0 1 0 1 0 1
0 0 0 0 0
SBOND¶
Bonding information. Lists pairs of elements and specifications for when and how to draw bonds between them.
Geometry edited in Edit > Bonds.
Appearance edited in Properties > Bonds > Radius and color. Edits all existing bonds at once, but not any new ones strangely enough.
Also Objects > Bonds.
Search mode:
Search A2 bonded to A1 (boundary mode defaults to 2)
Search atoms bonded to A1 (sets A2 to
XX
) (boundary mode defaults to 2)Search molecules (sets A1 and A2 to
XX
) (boundary mode defaults to 3)
Boundary mode:
Do not search atoms beyond the boundary.
Search additional atoms if A1 is included in the boundary.
Search additional atoms recursively if either A1 or A2 is visible.
Style:
Unicolor cylinder
Bicolor cylinder (default for standard bonds)
Color line
Gradient line
Dotted line
Dashed line (default for hydrogen bonds)
Each row:
1st item: Index.
2nd item: A1 (Atom 1).
3rd item: A2 (Atom 2).
4th item: Minimum length.
5th item: Maximum length.
6th item: Search mode - 1.
7th item: Boundary mode - 1.
8th item: Show polyhedra, 0/1.
9th item: Search by label, 0/1. If 1, A1 and A2 are site labels rather than element symbols.
10th item: Style - 1.
11th item: Radius (cylinder). Default
0.250
.12th item: Width (line). Default
2.000
. Units px.13th-15th items: Bond color (RGB) (may be overridden by atom colours depending on bond style). (Default
127 127 127
, but can be edited individually in Objects > Bonds.)
Block ends with four 0
’s.
e.g.
SBOND
1 B N 0.00000 1.93846 0 1 1 0 1 0.250 2.000 127 127 127
0 0 0 0
SITET¶
Site-specific appearances.
Each row:
1st item: Site index (see STRUC)
2nd item: Site label (see STRUC).
3rd item: Atomic radius (Objects > Properties > Atoms > Radius and color)
4-6th item: RGB of atom colour (Objects > Properties > Atoms > Radius and color)
7-9th item: Default atom colour (RGB)?
10th item: ?
11th item: ?
Ends with a row of 6 zero’s.
See ATOMT for global atomic properties. SITET overrides appearances set by ATOMT. New sites inherit from ATOMT.
e.g.
SITET
1 Cu 1.2800 34 71 220 34 71 220 204 0
0 0 0 0 0 0
VECTR¶
Vectors to draw on the atoms.
There are multiple blocks, one for each vector specification, which may be attached to multiple atoms. Each block is terminated by five 0
’s.
The whole section is terminated by another row of five 0
’s.
In each block:
1st row:
1st item: vector index.
2nd-4th items: vector coordinates, modulus along crystallographic axes (i.e. a basis of unit vectors parallel to the lattice vectors). (default 0 0 c-axis-length)
5th item: 0/1 axial/polar vector. (default 0)
2nd+ rows (optional):
1st item: site index to attach this vector to.
2nd item: 0 if crystallographic site, 1+ if individual site (default 0). Values >1 occur for symmetric images under symmetry group transformation (e.g. If you have P2, and a site with structure parameter (0.2,0,0), then you have an image at (-0.2,0,0); that site would have a value of 2 here.).
3rd-5th items: Number of unit cells/lattice vectors away from the original site, in x, y, and z directions (default 0,0,0).
Files lacking vectors have an empty VECTR block with just 0 0 0 0 0
.
e.g.
VECTR
1 0.40825 0.40825 0.40825 0
1 0 0 0 0
0 0 0 0 0
2 0.40825 0.40825 -1.22474 0
2 0 0 0 0
0 0 0 0 0
3 -0.40825 1.22474 -0.40825 0
3 0 0 0 0
0 0 0 0 0
4 1.22474 -0.40825 -0.40825 0
4 0 0 0 0
0 0 0 0 0
0 0 0 0 0
VECTT¶
Vector formatting.
1st item: vector index (see VECTR).
2nd item: Radius (0.5 is default)
3-5 items: RGB (0-255). (255 0 0 is default)
6th item: +1 if vector penetrates atom (end goes out both sides); +2 if we add atom radius to vector length. 1 is default.
e.g.
VECTT
1 0.350 255 0 0 1
2 0.350 255 0 0 1
3 0.350 255 0 0 1
4 0.350 255 0 0 1
0 0 0 0 0
SPLAN¶
Section planes of volumetric data.
Edit Data > Lattice Planes > Add lattice planes
For each row,
1st item: Number/index?
2-4th items: hkl Miller indices
5th item: Distance from origin (Angstrom)
6-9th items: Color (RGBA).
Section ends with four 0
’s.
e.g.
SPLAN
1 1.509013E+00 -1.000000E+00 1.014961E+02 5.35356 255 0 255 192
0 0 0 0
LBLAT¶
e.g.
LBLAT
-1
LBLSP¶
e.g.
LBLSP
-1
DLATM¶
Delete/hides the specified atoms. Objects > Atoms.
However, the atoms are not indexed by the expected indices. Instead, they are indexed by an internal index, which has a unique 0-based index for every single atom, including those in adjacent unit cells. It seems to be sorted by site. So first the index exhausts all atoms of the first site type, then the second, and so on. So a single site has a continuous set of indices.
Format: a list of integers (indices), terminated with a -1
.
e.g.
DLATM
1 2 3 -1
DLBND¶
Deletes/hides the specified bonds. Objects > Bonds.
However, as for DLATM, the indices are different to the usual indices, instead with each drawn object being given a different 0-based index.
Format: a list of integers (indices), terminated with a -1
.
e.g.
DLBND
-1
DLPLY¶
e.g.
DLPLY
-1
PLN2D¶
e.g.
PLN2D
0 0 0 0
ATOMT¶
Atomic/elemental appearance information.
Each row:
1st item: Index/number of element.
2nd item: Element symbol (see STRUC).
3rd item: Atomic radius (Objects > Properties > Atoms > Radius and color)
4-6th item: RGB of atom colour (Objects > Properties > Atoms > Radius and color)
7-9th item: RGB of something else? Default atom colour?
10th item: ?
Ends with a row of 6 zero’s.
See SITET. New sites inherit from ATOMT, although SITET overrides the appearance of individual sites.
e.g.
ATOMT
1 Cu 1.2800 34 71 220 34 71 220 204
0 0 0 0 0 0
Default values are derived from elements.ini
.
Column 1: atomic number
Column 2: Elemental symbol
Column 3: Atomic radius
Column 4: van der Waals radius
Column 5: Ionic radius
Columns 6-8: RGB colour (0-1) Which radius is used is based on the atomic radii type within ATOMS. Changing this setting through the UI overwrites all existing radii with the appropriate default values.
SCENE¶
View of the structure.
This parameter is modified by the view control bar at the top of the GUI window.
First 4 lines: affine matrix describing the camera angle. Only the first 3x3 elements seem to be used; no translation component appears to be added here via the GUI.
5th line: Horizontal and vertical displacement, in units of half the screen width. Default
0.000 0.000
.6th line: Zero.
0.000
.7th line: Zoom, as a multiplier (default
1.000
). (Can also be set indirectly through View > Overall Appearance > Scale.)
e.g.
SCENE
0.000000 1.000000 0.000000 0.000000
0.000000 0.000000 1.000000 0.000000
1.000000 0.000000 0.000000 0.000000
0.000000 0.000000 0.000000 1.000000
0.000 0.000
0.000
1.000
HBOND¶
e.g.
HBOND 0 2
STYLE¶
A newline precedes this section. No data is directly connected to the STYLE header. However, it appears to serve as a top-level header for various style-related tags.
STYLE
DISPF¶
Miscellaneous display flags, as binary bits.
+2: “Show models” is true.
+2048: “Hide non-bonding atoms” is true (Properties > Atoms > Atom style)
+4096: Enable depth-cueing (View > Overall Appearance > Depth-cueing)
+8192: Isosurface render from front-to-back (Properties > Isosurfaces).
+66536: “Show dot surface” is true.
+131072: “Show as displacement ellispoids” instead of “Show as balls” (Properties > Atoms > Atom style)
+2097152: Perspective projection (View > Overall Appearance > Projection)
+33554432: “Scale isotropic atoms by Uiso” (Properties > Atoms > Atom style)
e.g.
DISPF 37753794
MODEL¶
Structural model settings.
1st item: Style (integer flag)
0: Ball-and-stick
1: Space-filling
2: Polyhedral
3: Wireframe
4: Stick
2nd item: 1 if Show models, 0 if not.
3rd item: 1 if Show dot surface, 0 if not.
e.g.
MODEL 0 1 0
SURFS¶
e.g.
SURFS 0 1 1
SECTS¶
Flags for display of sections.
Properties > Sections.
1st item: Binary flag of properties. Default
32
.+1 if using “Absolute values” in Sections and slices.
+2 if using “Assign colors recursively” in Sections and slices.
+8 if SECCL is Y-M-C or C-M-Y.
+16 if SECCL is gray scale or rainbow+ or cyclic.
+128 if isosurfaces’ sections is set to Manual instead of Auto.
2nd item: ? Default
1
.
e.g.
SECTS 32 1
FORMS¶
e.g.
FORMS 0 1
ATOMS¶
Atom display settings.
Properties > Atoms > Atom style
1st item: Atom radii type. Default 0.
0: Atomic (default)
1: Ionic
2: van der Waals
2nd item: 0 if “Show as balls”. 1 if “Show as displacement ellipsoids”.
3rd item: 1: “Scale isotropic atoms by Uiso”. 0: “Set radii of isotropic atoms as specified below”.
e.g.
ATOMS 0 0 1
BONDS¶
e.g.
BONDS 1
POLYS¶
e.g.
POLYS 1
VECTS¶
Global scaling factor for vectors.
Edit > Vectors > Scale factor for modulus
e.g.
VECTS 1.000000
FORMP¶
e.g.
FORMP
1 1.0 0 0 0
ATOMP¶
Atom style properties.
Properties > Atoms > Atom style.
3rd item: True/false 1/0 flag. “Show principal ellipses.”
4th item: Displacement ellipsoids probability.
5th item: Outline width (of principal ellipses).
6th item: True/false 1/0 flag. “Hide non-bonding atoms”.
e.g.
ATOMP
24 24 0 50 2.0 0
BONDP¶
Bond style properties.
Properties > Bonds > Resolution
Properties > Bonds > Radius and color
Strangely, the radius and color data seem to be ignored when creating new bonds in favour of the defaults in style.ini.
1st item: Resolution > Stacks
2nd item: Resolution > Slices
3rd item: Radius and color > Radius (cylinder)
4th item: Radius and color > Width (line)
5-7th items: Radius and color > Color; RGB.
e.g.
BONDP
1 16 0.250 2.000 127 127 127
POLYP¶
e.g.
POLYP
204 1 1.000 180 180 180
ISURF¶
Isosurfaces.
From Properties > Isosurfaces > Isosurfaces, the table there.
Each row is an isosurface.
1st item: index/number?
2nd item: mode flag?
3rd item: isosurface level.
4-6th item: RGB colour of isosurface.
7th item: Opacity 1 (0-255)
8th item: Opacity 2 (0-255)
e.g.
ISURF
1 1 0.55903 255 255 0 127 255
0 0 0 0
TEX3P¶
e.g.
TEX3P
1 0.00000E+00 1.00000E+00
SECTP¶
Section planes, properties.
Objects > Properties > Sections
1st item: Whether colour scale is forwards (
1
) or inverted (-1
) (depends on SECCL).2nd item: Saturation levels minimum
3rd item: Saturation levels maximum
4th item: Cutoff level, for lattice planes, minimum
5th item: Cutoff level, for lattice planes, maximum
6th item: Cutoff level, for isosurfaces’s sections, minimum
7th item: Cutoff level, for isosurfaces’s sections, maximum
Reversed colour scales are: R-G-B, Y-M-C, cyclic R-G-B-R, and scales labelled as inverted.
e.g.
SECTP
1 0.00000E+00 1.00000E+00 0.00000E+00 0.00000E+00 0.00000E+00 0.00000E+00
CONTR¶
e.g.
CONTR
0.1 -1 1 1 10 -1 2 5
2 1 2 1
0 0 0
0 0 0
0 0 0
0 0 0
HKLPP¶
e.g.
HKLPP
192 1 1.000 255 0 255
UCOLP¶
Unit cell line properties.
Properties > General > Unit cell
1st item: Line style flag.
0
if solid lines (default).1
if dotted lines.2
if dashed lines.2nd item: Line visibility flag.
0
if do not show.1
single unit cell (default).2
if show all.3rd item: Line width (float), default 1.000.
4-6th item: RGB line colour.
e.g.
UCOLP
0 1 1.000 0 0 0
COMPS¶
Compass settings.
Properties > General > Axes.
Single integer flag.
0 : Do not show compass.
1 : Show compass and show axes. (Default)
2 : Show compass, do not show axes.
e.g.
COMPS 1
LABEL¶
e.g.
LABEL 1 12 1.000 0
PROJT¶
Projection.
View > Overall Appearance > Projection
1st item: Flag. 0: Parallel. 1: Perspective. See also DISPF.
2nd item: Viewpoint (for perspective). Ranges from 0.5 (far) to 2.0 (close).
e.g.
PROJT 0 0.962
BKGRC¶
Background colour.
View > Overall Appearance > Background Color
R G B
e.g.
BKGRC
255 255 255
DPTHQ¶
Depth cueing.
View > Overall Appearance > Depth-cueing
1st item: 1/0 true/false, Enable depth-cueing. (See DISPF.)
2nd item: Starting depth (float, Angstrom).
3rd item: Ending depth (float, Angstrom).
e.g.
DPTHQ 1 -0.5000 3.5000
LIGHT0¶
Lighting.
View > Overall Appearance > Light
LIGHT0 line: true/false 1/0 “Enable lighting”.
1st-4th lines: Affine rotation matrix for direction of incident light. Identity matrix (default) is from direction of view.
5th line: ? Default 0 0 20 0
6th line: ? Default 0 0 -1
7th line: Ambient, X X X 255, where X is converted from percent to 0-255, rounded to integer.
8th line: Diffuse, X X X 255, where X is converted from percent to 0-255, rounded to integer.
9th line: 255 255 255 255.
e.g.
LIGHT0 1
1.000000 0.000000 0.000000 0.000000
0.000000 1.000000 0.000000 0.000000
0.000000 0.000000 1.000000 0.000000
0.000000 0.000000 0.000000 1.000000
0.000000 0.000000 20.000000 0.000000
0.000000 0.000000 -1.000000
26 26 26 255
179 179 179 255
255 255 255 255
LIGHT1¶
e.g.
LIGHT1
1.000000 0.000000 0.000000 0.000000
0.000000 1.000000 0.000000 0.000000
0.000000 0.000000 1.000000 0.000000
0.000000 0.000000 0.000000 1.000000
0.000000 0.000000 20.000000 0.000000
0.000000 0.000000 -1.000000
0 0 0 0
0 0 0 0
0 0 0 0
LIGHT2¶
e.g.
LIGHT2
1.000000 0.000000 0.000000 0.000000
0.000000 1.000000 0.000000 0.000000
0.000000 0.000000 1.000000 0.000000
0.000000 0.000000 0.000000 1.000000
0.000000 0.000000 20.000000 0.000000
0.000000 0.000000 -1.000000
0 0 0 0
0 0 0 0
0 0 0 0
LIGHT3¶
e.g.
LIGHT3
1.000000 0.000000 0.000000 0.000000
0.000000 1.000000 0.000000 0.000000
0.000000 0.000000 1.000000 0.000000
0.000000 0.000000 0.000000 1.000000
0.000000 0.000000 20.000000 0.000000
0.000000 0.000000 -1.000000
0 0 0 0
0 0 0 0
0 0 0 0
SECCL¶
Section colour scheme.
Objects > Properties > Sections > Sections and slices.
Integer flag indicating option.
0 : B-G-R
1 : R-G-B
2 : C-M-Y
3 : Y-M-C
4 : Gray scale
5 : Inverted gray scale
6 : Rainbow+
7 : Inverted Rainbow+
8 : Cyclic: B-G-R-B
9 : Cyclic: R-G-B-R
10 : Cyclic: Ostwald
11 : Cyclic: Inverted Ostwald
12 : Cyclic: W-R-K-B-W
13 : Cyclic: K-R-W-B-K
e.g.
SECCL 0
TEXCL¶
A blank line precedes and follows this section.
e.g.
TEXCL 0
ATOMM¶
Atom material.
Properties > Atoms > Material
1st line: R, G, B, A(? Doesn’t change from 255.)
2nd line: Shininess, float, percentage x 1.28. (So on scale from 1.280 to 128.000.)
e.g.
ATOMM
204 204 204 255
25.600
BONDM¶
e.g.
BONDM
255 255 255 255
128.000
POLYM¶
e.g.
POLYM
255 255 255 255
128.000
SURFM¶
e.g.
SURFM
0 0 0 255
128.000
FORMM¶
e.g.
FORMM
255 255 255 255
128.000
HKLPM¶
e.g.
HKLPM
255 255 255 255
128.000