VestaFile

This is the core class of vestacrystparser. It is a complete representation of a VESTA file.

class vestacrystparser.VestaFile(filename: str | None = None)

Representation of a VESTA file, with methods to manipulate it.

sections

Maps section headers to VestaSection objects.

Type:

dict

order

The order in which sections appear in the file.

Type:

list

__contains__(name: str | tuple[str, int]) → bool

Contains the specified Section?

Parameters:

name – either name (str) or tuple (name, phase) (str, int). phase defaults to self.current_phase.

Returns:

True or False.

__getitem__(name: str | tuple[str, int]) → VestaSection

Returns the section with the given name (and optionally phase)

Called as either self[name] or self[name, phase].

phase defaults to self.current_phase.

Parameters:

name – Either the section name (str), or a tuple of the name (str) and the phase (int) (0-based). Some sections are global rather than tied to a phase. In such cases, the phase is ignored.

Raises:

  • IndexError – Invalid phase given.

  • KeyError – Invalid name given.

__init__(filename: str | None = None)

Initialize a VESTA file instance.

__iter__() → Iterator[VestaSection]

Iterate over the sections

__len__() → int

Returns total number of sections.

__repr__() → str

Compact representation. Titles and number of sites of each phase.

__str__() → str

Return entire VestaFile as multi-line string

add_bond(A1: str, A2: str, min_length: float = 0.0, max_length: float = 1.6, search_mode: int = 1, boundary_mode: int | None = None, show_polyhedra: bool = True, search_by_label: bool = False, style: int = 2)

Add a new bond type.

Mimics Edit > Bonds.

Parameters:

  • A1 – Atoms to bond.

  • A2 – Atoms to bond.

  • min_length – Minimum bond length (Angstrom).

  • max_length – Maximum bond length (Angstrom).

  • search_mode –

    • 1 = Search A2 bonded to A1 (default)

    • 2 = Search atoms bonded to A1. (Overwrites A2 to be ‘XX’.)

    • 3 = Search molecules. (Overwrites A1 and A2 to be ‘XX’.)

  • boundary_mode –

    • 1 = Do not search atoms beyond the boundary.

    • 2 = Search additional atoms if A1 is included in the boundary. (default for search_mode = 1 or 2)

    • 3 = Search additional atoms recursively if either A1 or A2 is visible. (default for search_mode = 3)

  • show_polyhedra – Draw polyhedra using this bond.

  • search_by_label – If True, interpret A1 and A2 as site labels. If False, interpret A1 and A2 as element symbols.

  • style –

    • 1 = Unicolor cylinder

    • 2 = Bicolor cylinder (default for standard bonds)

    • 3 = Color line

    • 4 = Gradient line

    • 5 = Dotted line

    • 6 = Dashed line (default for hydrogen bonds)

Related sections: SBOND

add_lattice_plane(h: float, k: float, l: float, distance: float, r: int = 255, g: int = 0, b: int = 255, a: int = 192)

Adds a lattice plane, sectioning the volumetric data.

Mimics Edit Data > Lattice Planes > Add lattice planes.

Parameters:

  • h – Miller indices of the plane.

  • k – Miller indices of the plane.

  • l – Miller indices of the plane.

  • distance – distance from origin (Angstrom)

  • r – colour values (0-255) of section. Default is magenta.

  • g – colour values (0-255) of section. Default is magenta.

  • b – colour values (0-255) of section. Default is magenta.

  • a – colour values (0-255) of section. Default is magenta.

Related sections: SPLAN

add_site(symbol: str, label: str, x: float, y: float, z: float, dx: float = 0.0, dy: float = 0.0, dz: float = 0.0, occupation: float = 1.0, charge: float = 0.0, U: float = 0.0, add_bonds: bool = False)

Adds a new site.

Parameters:

  • symbol – Element symbol.

  • label – Name of site.

  • x – Coordinates of position (fraction of lattice vectors).

  • y – Coordinates of position (fraction of lattice vectors).

  • z – Coordinates of position (fraction of lattice vectors).

  • dx – Uncertainty in coordinates.

  • dy – Uncertainty in coordinates.

  • dz – Uncertainty in coordinates.

  • occupation – Site occupation (0-1).

  • charge – Charge on site.

  • U – ??? Something to do with thermal uncertainty in position.

  • add_bonds – Create new bonds if applicable. While not the default behaviour in VESTA, this is provided as a convenience function.

Related sections: STRUC, THERI, THERM, ATOMT, SITET, ATOMS, SBOND

add_vector_type(x: float, y: float, z: float, polar: bool = False, radius: float = 0.5, r: int = 255, g: int = 0, b: int = 0, penetrate_atoms: bool = True, add_atom_radius: bool = False, coord_type: str = 'xyz')

Create a new type of vector.

Mimics Edit > Vectors > New.

Parameters:

  • x (float) – Coordinates of vector.

  • y (float) – Coordinates of vector.

  • z (float) – Coordinates of vector.

  • polar (bool) – Whether this is a polar vector (rather than axial). Default False.

  • radius (float (positive)) – Radius of rendered arrow. Default 0.5.

  • r (int) – 0-255. RGB colour of vector. Default 255, 0, 0.

  • g (int) – 0-255. RGB colour of vector. Default 255, 0, 0.

  • b (int) – 0-255. RGB colour of vector. Default 255, 0, 0.

  • penetrate_atoms (bool) – Whether the vector penetrates the atom, such that it sticks out on both sides. Default True.

  • add_atom_radius (bool) – Whether to add the atomic radius to the length of the vector. Default False.

  • coord_type ("xyz", "uvw", "modulus") –

    Coordinate basis for x, y, z arguments.

    • ”xyz”: Cartesian vector notation. (Default)

    • ”uvw”: Lattice vector notation.

    • ”modulus”: Modulus along crystallographic axes. (This is the internal representation.)

Related sections: VECTR, VECTT.

delete_bond(index: int)

Deletes the specified bond type.

Parameters:

index – Index of bond (1-based). Accepts negative indices, counting from the end.

Related sections: SBOND

delete_isosurface(index: int)

Deletes an isosurface, specified by index.

Parameters:

index – 1-based index. Accepts negative indices, counting from the end.

Related section: ISURF.

delete_lattice_plane(index: int)

Deletes a lattice plane, specified by index.

Parameters:

index – 1-based index. Accepts negative indices, counting from the end.

Related sections: SPLAN

delete_vector_type(index: int)

Delete the given vector type.

Parameters:

index – Index of vector, 1-based. Negative indices accepted.

Related sections: VECTT, VECTR

distance(x1: float, y1: float, z1: float, x2: float, y2: float, z2: float) → float

Return the Cartesian distance between two points (given in fractional coordinates).

edit_bond(index: int, A1: str = None, A2: str = None, min_length: float = None, max_length: float = None, search_mode: int = None, boundary_mode: int | None = None, show_polyhedra: bool = None, search_by_label: bool = None, style: int = None, radius: float = None, width: float = None, r: int = None, g: int = None, b: int = None)

Edits an existing bond.

Mimics Edit > Bonds.

All arguments after index are optional. Unset arguments are left unchanged.

N.B. If you are reducing search mode, remember to set A2 or A1, otherwise they’ll be left at ‘XX’.

Parameters:

  • index – Index of bond (1-based). Accepts negative indices, counting from the end.

  • A1 – Atoms to bond.

  • A2 – Atoms to bond.

  • min_length – Minimum bond length (Angstrom).

  • max_length – Maximum bond length (Angstrom).

  • search_mode –

    • 1 = Search A2 bonded to A1 (default)

    • 2 = Search atoms bonded to A1. (Overwrites A2 to be ‘XX’.)

    • 3 = Search molecules. (Overwrites A1 and A2 to be ‘XX’.)

  • boundary_mode –

    • 1 = Do not search atoms beyond the boundary.

    • 2 = Search additional atoms if A1 is included in the boundary. (default for search_mode = 1 or 2)

    • 3 = Search additional atoms recursively if either A1 or A2 is visible. (default for search_mode = 3)

  • show_polyhedra – Draw polyhedra using this bond.

  • search_by_label – If True, interpret A1 and A2 as site labels. If False, interpret A1 and A2 as element symbols.

  • style –

    • 1 = Unicolor cylinder

    • 2 = Bicolor cylinder (default for standard bonds)

    • 3 = Color line

    • 4 = Gradient line

    • 5 = Dotted line

    • 6 = Dashed line (default for hydrogen bonds)

Related sections: SBOND

edit_vector_type(index: int, x: float = None, y: float = None, z: float = None, polar: bool = None, radius: float = None, r: int = None, g: int = None, b: int = None, penetrate_atoms: bool = None, add_atom_radius: bool = None, coord_type: str = 'xyz')

Edits an existing type of vector.

Mimics Edit > Vectors > Edit.

Accepts negative indices, counting from the end.

All arguments after index are optional. Unset arguments are left unchanged. If x, y, or z are provided, all of x, y, and z need to be provided.

Parameters:

  • index (int) – Index (1-based) of the vector.

  • x (float) – Coordinates of vector.

  • y (float) – Coordinates of vector.

  • z (float) – Coordinates of vector.

  • polar (bool) – Whether this is a polar vector (rather than axial). Default False.

  • radius (float (positive)) – Radius of rendered arrow. Default 0.5.

  • r (int) – 0-255. RGB colour of vector. Default 255, 0, 0.

  • g (int) – 0-255. RGB colour of vector. Default 255, 0, 0.

  • b (int) – 0-255. RGB colour of vector. Default 255, 0, 0.

  • penetrate_atoms (bool) – Whether the vector penetrates the atom, such that it sticks out on both sides. Default True.

  • add_atom_radius (bool) – Whether to add the atomic radius to the length of the vector. Default False.

  • coord_type ("xyz", "uvw", "modulus") –

    Coordinate basis for x, y, z arguments.

    • ”xyz”: Cartesian vector notation. (Default)

    • ”uvw”: Lattice vector notation.

    • ”modulus”: Modulus along crystallographic axes. (This is the internal representation.)

Related sections: VECTR, VECTT.

find_sites(elements: list[str] | str | None = None, xmin: float = 0, xmax: float = 1, ymin: float = 0, ymax: float = 1, zmin: float = 0, zmax: float = 1) → list[int]

Return the site indices of matching element in the given box.

Parameters:

  • elements – Optional. Element symbol(s) of the sites to find. If not provided, find all elements.

  • xmin – Extent of the bounding box for the search (fractional coordinates).

  • xmax – Extent of the bounding box for the search (fractional coordinates).

  • ymin – Extent of the bounding box for the search (fractional coordinates).

  • ymax – Extent of the bounding box for the search (fractional coordinates).

  • zmin – Extent of the bounding box for the search (fractional coordinates).

  • zmax – Extent of the bounding box for the search (fractional coordinates).

Fractional coordinates of sites are probably in the interval [0,1).

get_bonds() → list[dict]

Return a list of what bond types exist.

Each element is a dictionary, which can be used directly as keyword arguments for add_bond().

Data is a copy.

Returns:

List of dictionaries. Each dict represents a bond type and has the following keys:

A1:str, A2:str, min_length:float, max_length:float, search_mode:int, boundary_mode:int, show_polyhedra:bool, search_by_label:bool, style:int.

Related sections: SBOND

get_cell() → list[float, float, float, float, float, float]

Return a copy of the cell parameters: a,b,c,alpha,beta,gamma

Related sections: CELLP

get_cell_matrix() → list[list[float]]

Return the lattice vectors as a 3x3 matrix.

VESTA aligns the 1st lattice vectors with the x axis, and the 2nd in the x-y plane.

Related sections: CELLP.

get_structure() → list[list]

Return a list of the key site structure parameters.

Returned data is a copy.

Returns:

List of lists, with each sub-list being a site. It has the following properties: index (int), element (str), label (str), x (float), y (float), z (float).

Related sections: STRUC

load(filename)

Load and parse a VESTA file into this instance.

Parameters:

filename (str) – Path to the VESTA file.

property nphases: int

Number of phases (read-only)

property nsites: int

Number of sites in the current phase (read-only)

property nvectors: int

Number of vector types in the current phase (read-only)

remove_vector_from_site(type: int, site: int)

Removes vectors of type type from atomic site site.

Will remove multiple matching sites if there are duplicates.

Parameters:

  • type – Index (1-based) of vector.

  • site – Index (1-based) of site. Silently does nothing if site note found.

Raises:

IndexError – type is out of bounds.

Related sections: VECTR

reset_lighting_angle()

Resets the lighting angle to directly overhead.

Related sections: LIGHT0

save(filename)

Write the current VESTA data to disk.

Parameters:

filename (str) – Output file path.

set_atom_color(element: str | int, r: int, g: int, b: int, overwrite_site_colors: bool = True)

Sets the colour of all atoms of an element.

Parameters:

  • element – Element (by index or symbol) to modify.

  • r – Red value (0-255)

  • g – Green value (0-255)

  • b – Blue value (0-255)

  • overwrite_site_colors – Set existing sites of element to this colour (otherwise, only changes sites added later).

Related sections: ATOMT, SITET.

set_atom_material(r: int = None, g: int = None, b: int = None, shininess: float = None)

Sets the atom material for lighting purposes.

Unset parameters are left unchanged.

Parameters:

  • r – Colour values (0-255).

  • g – Colour values (0-255).

  • b – Colour values (0-255).

  • shininess – percentage (1-100).

Related sections: ATOMM

set_background_color(r: int, g: int, b: int)

Sets the background colour (RGB, 0-255).

Related sections: BKGRC

set_boundary(xmin: float = None, xmax: float = None, ymin: float = None, ymax: float = None, zmin: float = None, zmax: float = None)

Sets viewing Boundary.

Unset arguments are left unchanged.

Related sections: BOUND

set_cell(a: float = None, b: float = None, c: float = None, alpha: float = None, beta: float = None, gamma: float = None)

Set unit cell parameters.

Unset keyword arguments left unchanged.

Parameters:

  • a – Lattice vector lengths (Angstrom).

  • b – Lattice vector lengths (Angstrom).

  • c – Lattice vector lengths (Angstrom).

  • alpha – Lattice vector angles (degrees).

  • beta – Lattice vector angles (degrees).

  • gamma – Lattice vector angles (degrees).

Related sections: CELLP

set_compass_visibility(show: bool, axes: bool = True) → int

Set compass and axes label visibility.

Parameters:

  • show – Show the compass.

  • axes – Show the axes labels on the compass.

Returns:

Value of the flag that was set. 0: hidden. 1: compass only. 2: compass and labels.

Related sections: COMPS

set_current_phase(phase: int)

Sets the currently active phase by 0-based index.

__getitem__() calls, along with all set and get functions, will default to this phase.

Accepts negative indices in the Pythonic manner, but it is recorded as a positive index.

Parameters:

phase – Index to set the current phase to.

Raises:

IndexError – Out-of-bounds phase given.

set_depth_cueing(enable: bool = None, start: float = None, end: float = None)

Sets depth cueing settings.

Unset properties are left unchanged.

Parameters:

  • enable – Whether to use depth cueing.

  • start – Depth at which depth cueing begins.

  • end – Depth at which depth cueing ends.

Related sections: DPTHQ

set_enable_lighting(enable: bool)

Sets whether or not to Enable Lighting.

Related sections: LIGHT0

set_lighting(ambient: int = None, diffuse: int = None)

Sets the ambient and diffuse character of lighting, in percent.

Unset properties are left unchanged.

Related sections: LIGHT0

set_lighting_angle(matrix: list[list[float]])

Sets the angle for lighting, using a 3x3 rotation matrix.

Related sections: LIGHT0

set_scene_view_direction(view: str) → list[list[float]]

Set view direction to a preset viewing direction.

Parameters:

view – Preset viewing direction. Valid presets: “c”.

Returns:

The 3x3 matrix that was set.

Related sections: SCENE

set_scene_view_matrix(matrix)

Set the 3x3 rotation matrix describing viewing angle.

Parameters:

matrix (list[list] or array-like) – 3x3 rotation matrix.

Related sections: SCENE

set_scene_zoom(zoom: float)

Set zoom of the view.

Parameters:

zoom – 1 is VESTA default.

Related sections: SCENE

set_section_color_scheme(scheme: int | str)

Sets the colour scheme of volumetric sections.

Mimics Properties > Sections > Sections and slices, from the drop-down menu.

Parameters:

scheme – either a string with the exact name of the colour scheme, or an integer (0-based) indexing the item’s position in the list.

Colour schemes:

“B-G-R”, “R-G-B”, “C-M-Y”, “Y-M-C”, “Gray scale”, “Inverted gray scale”, “Rainbow+”, “Inverted Rainbow+”, “Cyclic: B-G-R-B”, “Cyclic: R-G-B-R”, “Cyclic: Ostwald”, “Cyclic: Inverted Ostwald”, “Cyclic: W-R-K-B-W”, “Cyclic: K-R-W-B-K”.

Related sections: SECCL, SECTP, SECTS

set_section_cutoff_levels(lattice_min: float = None, lattice_max: float = None, isosurface_min: float = None, isosurface_max: float = None, isosurface_auto: bool = None)

Sets cutoff levels for volumetric sections

Mimics Properties > Sections > Cutoff levels

Unset keyword arguments are left unchanged.

Related sections: SECTP, SECTS

set_site_color(index: int | list[int], r: int, g: int, b: int)

Set the RGB site colour for sites with index (1-based).

Supports setting multiple sites at once.

Parameters:

  • index – site index or list of site indices.

  • r (int) – Red value (0-255).

  • g (int) – Green value (0-255).

  • b (int) – Blue value (0-255).

Related sections: SITET.

set_title(title: str)

Sets the TITLE field. No newlines allowed.

set_unit_cell_line_visibility(show: bool = None, all: bool = False) → int

Sets the visibility of the unit cell(s).

Parameters:

  • show – If False, hide the unit cell. If True, show the unit cell.

  • all – If True, show all unit cells. show=False takes precedence, but also throws a warning if you try setting both. Setting all=False without specifying show changes nothing and throws a warning.

Returns:

Value of the flag that was set. 0: hidden. 1: show single cell. 2: show all cells.

Related sections: UCOLP

set_vector_scale(scale: float)

Sets global vector scale factor (VECTS)

set_vector_to_site(type: int, site: int)

Attach a vector of type type to atomic site.

Currently, we attach to all symmetrically equivalent sites based on the current space group. We do not have an option to attach to specific atoms. Also, no duplicate checking is performed.

Parameters:

  • type – Index (1-based) of vector.

  • site – Index (1-based) of site.

Raises:

IndexError – type or site are out of bounds.

Related sections: VECTR

sort_bonds(unmatching_bonds: str = 'before')

Rearranges the list of bonds to be in the order provided in sbond.csv.

Because when VESTA loads a POSCAR, it has SBOND in this order, rather than the order that sites appear. (Which suggests is generates SBOND after generating all the sites, but whatever, as long as the result is the same.)

Parameters:

unmatching_bands – “before” or “after”. Where to put bonds that don’t appear in sbond.csv.

Related sections: SBOND

property title: str

Title of the current phase (settable)

unhide_atoms()

Unhides all hidden atoms (DLATM)

unhide_bonds()

Unhides all hidden bonds (DLBND)

unhide_polyhedra()

Unhides all hidden polyhedra (DLPLY)