Topology¶

class py4vasp.data.Topology(data_context, **kwargs)¶

Bases: Refinery

This class accesses the topology of the crystal.

At the current stage this only provides access to the name of the atoms in the unit cell, but one could extend it to identify logical units like the octahedra in perovskites.

Attributes Summary

path	Returns the path from which the output is obtained.

Methods Summary

elements()	Extract the element of all atoms.
from_data(raw_data)	Create the instance directly from the raw data.
from_file(file)	Read the quantities from the given file.
from_path([path])	Read the quantities from the given path.
ion_types()	Return the type of all ions in the system as string.
names()	Extract the labels of all atoms.
number_atoms()	Return the number of atoms in the system.
print()	Print a string representation of this instance.
read(*args, **kwargs)	Convenient wrapper around to_dict.
to_POSCAR([format_newline])	Generate the topology lines for the POSCAR file.
to_dict()	Read the topology and convert it to a dictionary.
to_frame()	Convert the topology to a DataFrame
to_mdtraj()	Convert the topology to a mdtraj.Topology.

Attributes Documentation

path¶

Returns the path from which the output is obtained.

Methods Documentation

elements()¶

Extract the element of all atoms.

classmethod from_data(raw_data)¶

Create the instance directly from the raw data.

Use this approach when the data is put into the correct format by other means than reading from the VASP output files. A typical use case is to read the data with from_path and then act on it with some postprocessing and pass the results to this method.

Parameters:

raw_data – The raw data required to produce this Refinery.

Return type:

A Refinery instance to handle the passed data.

classmethod from_file(file)¶

Read the quantities from the given file.

You want to use this method if you want to avoid using the Calculation wrapper, for example because you renamed the output of the VASP calculation.

Parameters:

file (str or io.BufferedReader) – Filename from which the data is extracted. Alternatively, you can open the file yourself and pass the Reader object. In that case, you need to take care the file is properly closed again and be aware the generated instance of this class becomes unusable after the file is closed.

Returns:

The returned instance handles opening and closing the file for every function called on it, unless a Reader object is passed in which case this is left to the user.

Return type:

Refinery

Notes

VASP produces multiple output files whereas this routine will only link to the single specified file. Prefer from_path routine over this method unless you renamed the VASP output files, because from_path can collate results from multiple files.

classmethod from_path(path=None)¶

Read the quantities from the given path.

The VASP schema determines the particular files accessed. The files will only be accessed when the data is required for a particular postprocessing call.

Parameters:

path (str or pathlib.Path) – Path to the directory with the outputs of the VASP calculation. If not set explicitly the current directory will be used.

Returns:

The returned instance handles opening and closing the files for every function called on it.

Return type:

Refinery

ion_types()¶

Return the type of all ions in the system as string.

names()¶

Extract the labels of all atoms.

number_atoms()¶

Return the number of atoms in the system.

print()¶

Print a string representation of this instance.

read(*args, **kwargs)¶

Convenient wrapper around to_dict. Check that function for examples and optional arguments.

to_POSCAR(format_newline='')¶

Generate the topology lines for the POSCAR file.

Parameters:

format_newline (str) – If you want to display the POSCAR file in a particular way, you can use an additional string to add formatting.

Returns:

A string used to describe the atoms in the system in the POSCAR file augmented by the additional formatting string, if given.

Return type:

str

to_dict()¶

Read the topology and convert it to a dictionary.

Returns:

A map from particular labels to the corresponding atom indices. For every atom a single label of the form Element*_*Number (e.g. Sr_1) is constructed. In addition there is a map from atoms of a specific element type to all indices of that element and from atom-indices strings to atom-indices integers. These access strings are used throughout all of the refinement classes.

Return type:

dict

to_frame()¶

Convert the topology to a DataFrame

Returns:

The dataframe matches atom label and element type.

Return type:

pd.DataFrame

to_mdtraj()¶

Convert the topology to a mdtraj.Topology.