Structure¶

class py4vasp.data.Structure(*args, **kwargs)¶

Bases: Mixin, Refinery

The structure of the crystal for selected steps of the simulation.

You can use this class to process structural information from the Vasp calculation. Typically you want to do this to inspect the converged structure after an ionic relaxation or to visualize the changes of the structure along the simulation.

Examples

If you access a method of this class, the result will depend on the steps that you selected with the [] operator. Without any selection the results from the final step will be used.

>>> calc.structure.read()

To select the results for all steps, you don’t specify the array boundaries.

>>> calc.structure[:].read()

You can also select specific steps or a subset of steps as follows

>>> calc.structure[5].read()
>>> calc.structure[1:6].read()

Attributes Summary

A_to_nm	Converting Å to nm used for mdtraj trajectories.
path	Returns the path from which the output is obtained.

Methods Summary

cartesian_positions()	Convert the positions from direct coordinates to cartesian ones.
from_POSCAR(poscar)	Generate a structure from string in POSCAR format.
from_ase(structure)	Generate a structure from the ase Atoms class.
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.
number_atoms()	Return the total number of atoms in the structure.
number_steps()	Return the number of structures in the trajectory.
plot([supercell])	Generate a 3d representation of the structure(s).
print()	Print a string representation of this instance.
read(*args, **kwargs)	Convenient wrapper around to_dict.
to_POSCAR()	Convert the structure(s) to a POSCAR format
to_ase([supercell])	Convert the structure to an ase Atoms object.
to_dict()	Read the structural information into a dictionary.
to_mdtraj()	Convert the trajectory to mdtraj.Trajectory
volume()	Return the volume of the unit cell for the selected steps.

Attributes Documentation

A_to_nm = 0.1¶

Converting Å to nm used for mdtraj trajectories.

path¶

Returns the path from which the output is obtained.

Methods Documentation

cartesian_positions()¶

Convert the positions from direct coordinates to cartesian ones.

Returns:

Position of all atoms in cartesian coordinates in Å.

Return type:

np.ndarray

Examples

If you access this method, the result will depend on the steps of the class that you selected with the [] operator. Without any selection the results from the final step will be used.

>>> calc.structure.cartesian_positions()

To select the results for all steps, you don’t specify the array boundaries.

>>> calc.structure[:].cartesian_positions()

You can also select specific steps or a subset of steps as follows

>>> calc.structure[5].cartesian_positions()
>>> calc.structure[1:6].cartesian_positions()

classmethod from_POSCAR(poscar)¶

Generate a structure from string in POSCAR format.

classmethod from_ase(structure)¶

Generate a structure from the ase Atoms class.

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

number_atoms()¶

Return the total number of atoms in the structure.

number_steps()¶

Return the number of structures in the trajectory.

plot(supercell=None)¶

Generate a 3d representation of the structure(s).

Parameters:

supercell (int or np.ndarray) – If present the structure is replicated the specified number of times along each direction.

Returns:

Visualize the structure(s) as a 3d figure.

Return type:

Viewer3d

Examples

If you access this method, the result will depend on the steps of the class that you selected with the [] operator. Without any selection the results from the final step will be used.

>>> calc.structure.to_graph()

To select the results for all steps, you don’t specify the array boundaries.

>>> calc.structure[:].to_graph()

You can also select specific steps or a subset of steps as follows

>>> calc.structure[5].to_graph()
>>> calc.structure[1:6].to_graph()

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()¶

Convert the structure(s) to a POSCAR format

Returns:

Returns the POSCAR of the current or all selected steps.

Return type:

str or list[str]

Examples

If you access this method, the result will depend on the steps of the class that you selected with the [] operator. Without any selection the results from the final step will be used.

>>> calc.structure.to_POSCAR()

To select the results for all steps, you don’t specify the array boundaries.

>>> calc.structure[:].to_POSCAR()

You can also select specific steps or a subset of steps as follows

>>> calc.structure[5].to_POSCAR()
>>> calc.structure[1:6].to_POSCAR()

to_ase(supercell=None)¶

Convert the structure to an ase Atoms object.

Parameters:

supercell (int or np.ndarray) – If present the structure is replicated the specified number of times along each direction.

Returns:

Structural information for ase package.

Return type:

ase.Atoms

Examples

If you access this method, the result will depend on the steps of the class that you selected with the [] operator. Without any selection the results from the final step will be used.

>>> calc.structure.to_ase()

To select the results for all steps, you don’t specify the array boundaries.

>>> calc.structure[:].to_ase()

You can also select specific steps or a subset of steps as follows

>>> calc.structure[5].to_ase()
>>> calc.structure[1:6].to_ase()

to_dict()¶

Read the structural information into a dictionary.

Returns:

Contains the unit cell of the crystal, as well as the position of all the atoms in units of the lattice vectors and the elements of the atoms for all selected steps.

Return type:

dict

Examples

If you access this method, the result will depend on the steps of the class that you selected with the [] operator. Without any selection the results from the final step will be used.

>>> calc.structure.to_dict()

To select the results for all steps, you don’t specify the array boundaries.

>>> calc.structure[:].to_dict()

You can also select specific steps or a subset of steps as follows

>>> calc.structure[5].to_dict()
>>> calc.structure[1:6].to_dict()

to_mdtraj()¶

Convert the trajectory to mdtraj.Trajectory

Returns:

The mdtraj package offers many functionalities to analyze a MD trajectory. By converting the Vasp data to their format, we facilitate using all functions of that package.

Return type:

mdtraj.Trajectory

Examples

If you access this method, the result will depend on the steps of the class that you selected with the [] operator. Without any selection the results from the final step will be used.

>>> calc.structure.to_mdtraj()

To select the results for all steps, you don’t specify the array boundaries.

>>> calc.structure[:].to_mdtraj()

You can also select specific steps or a subset of steps as follows

>>> calc.structure[5].to_mdtraj()
>>> calc.structure[1:6].to_mdtraj()

volume()¶

Return the volume of the unit cell for the selected steps.

Returns:

The volume(s) of the selected step(s) in ų.

Return type:

float or np.ndarray

Examples

If you access this method, the result will depend on the steps of the class that you selected with the [] operator. Without any selection the results from the final step will be used.

>>> calc.structure.volume()

To select the results for all steps, you don’t specify the array boundaries.

>>> calc.structure[:].volume()

You can also select specific steps or a subset of steps as follows

>>> calc.structure[5].volume()
>>> calc.structure[1:6].volume()