vestacrystparser.parser

Parse, modify, and write VESTA files, for visualisation of crystals.

VestaFile is the core class, while all other objects here support it. (VestaFile may also be imported from the top level, vestacrystparser.VestaFile.) Most functions can be completed using just this class’s methods.

VestaSection are the low-level building blocks of VestaFile, used when making low-level API calls.

The other functions and methods are primarily of use to developers.

class vestacrystparser.parser.VestaPhase

A collection of uniquely-named VestaSection’s

__contains__(name: str) → bool

Return True if VestaPhase contains a section with name.

__getitem__(name: str) → VestaSection

Return item by name of section. Raise KeyError if not present.

__init__()
__iter__() → Iterator[VestaSection]

Iterate over each section.

__len__() → int

Number of sections.

__weakref__

list of weak references to the object

append(section: VestaSection)

Add a new section to the phase.

VestaSection is added by reference, so you can keep modifying it.

Parameters:

section – VestaSection not already present.

Raises:

KeyError – section with the same header is already present.

property nsites: int

Number of sites (read-only)

property title: str

Title of the phase (read-only)

class vestacrystparser.parser.VestaSection(header_line: str)

Section of a VestaFile.

To create it, initialise with the header line (including in-line data). Then add subsequent lines with add_line().

header

Name of the section.

Type:

str

inline

List of in-line data (i.e. data that appears in the same line as the header, space-separated).

Type:

list

data

All other data, with one list for each line. Most data, when parsed, is split at whitespace. The exception is the TITLE, which is kept as a single string (e.g. [[“New structure”]]).

Type:

list[list]

raw_header

Unformatted and unsplit header line. Just in case you need it.

Type:

str

__init__(header_line: str)

Initialize a VESTA section from a header line.

For the TITLE section:

  • Inline data is not preserved on the header, but moved to the multi-line data.

For other sections:

  • If inline data is present on the header, it is stored (parsed) in self.inline.

  • Subsequent lines are stored in self.data.

Parameters:

header_line (str) – The complete header line (with any inline data).

__len__() → int

Return number of lines (besides the header line)

__str__() → str

Return the section as valid VESTA text.

  • If inline data exists, it is written on the header line.

  • Then, any extra lines are written one per line.

__weakref__

list of weak references to the object

add_line(line: str)

Append a line to the section.

For TITLE, store the entire line as a string. For other sections, split the line into tokens and convert them.

Parameters:

line – raw string of the line.

vestacrystparser.parser.invert_matrix(mat: list[list[float]]) → list[list[float]]

Inverts a 3x3 matrix.

vestacrystparser.parser.load_default_bond_length(A1: str, A2: str) → float | None

Returns default maximum bond length for a pair of elements (if present).

(N.B. If adding bonds manually, VESTA GUI defaults to 1.6.)

Parameters:

  • A1 – Pair of elements.

  • A2 – Pair of elements.

Returns:

Maximum bond length in Angstrom, if present.

May be None. Not every element pair has default bonds.

vestacrystparser.parser.load_default_bond_style(A1: str, A2: str, hbond: bool = False) → list[int, str, str, float, float, int, int, int, int, int] | None

Loads default bond style for a pair of elements (if present).

Loads data from sbond.csv.

(N.B. If adding bonds manually, VESTA GUI defaults to 1.6.)

Parameters:

  • A1 – Pair of element symbols. Order does not matter.

  • A2 – Pair of element symbols. Order does not matter.

  • hbond – If True, grab the hydrogen bond, if present. This is the second matching entry in sbond.csv

Returns:

May be None. Not every element pair has default bonds. If the element pair does have a bond, a list is returned:

  • index in sbond.csv,

  • A1,

  • A2,

  • minimum length,

  • maximum length,

  • search mode,

  • boundary mode,

  • show polyhedra,

  • 0 (search by label = False),

  • style (normal (1) or H-bond (5))

vestacrystparser.parser.load_elements_data(element: int | str) → list[int, str, float, float, float, int, int, int]

Load default data for a specific element.

Loads data from elements.csv.

Parameters:

element – Elemental symbol (str) or atomic number (int). If element is not present, falls back to “XX” (and logs it at INFO level).

Returns:

  • Atomic number (int).

  • Elemental symbol (str).

  • Atomic radius (float, Angstrom).

  • van der Waals radius (float, Angstrom).

  • Ionic radius (float, Angstrom).

  • Red colour value (int, 0-255).

  • Green colour value (int, 0-255).

  • Blue colour value (int, 0-255).

vestacrystparser.parser.parse_line(line: str) → list[int | float | str]

Split a line into tokens and convert each token.

Parameters:

line – String with data separated by spaces.

Returns:

A list of tokens (int, float, or string, as appropriate).

vestacrystparser.parser.parse_token(token: str) → int | float | str

Convert a token to int or float if possible (or leave as a string).

Parameters:

token – A string.

Returns:

token converted to int if possible, or else float if possible, or else returned as-is.