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.)
- 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.
- 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.)
- 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
- 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).
- 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_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”.
- 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.
- 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_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)