structure¶

The structure contains the unit cell and the position of all ions within.

The crystal structure is the specific arrangement of ions in a three-dimensional repeating pattern. This spatial arrangement is characterized by the unit cell and the relative position of the ions. The unit cell is repeated periodically in three dimensions to form the crystal. The combination of unit cell and ion positions determines the symmetry of the crystal. This symmetry helps understanding the material properties because some symmetries do not allow for the presence of some properties, e.g., you cannot observe a ferroelectric polarization in a system with inversion symmetry. Therefore relaxing the crystal structure with VASP is an important first step in analyzing materials properties.

When you run a relaxation or MD simulation, this class allows to access all individual steps of the trajectory. Typically, you would study the converged structure after an ionic relaxation or to visualize the changes of the structure along the simulation. Moreover, you could take snapshots along the trajectory and further process them by computing more properties.

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

A_to_nm = 0.1¶

Converting Å to nm used for mdtraj trajectories.

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, *, elements=None)¶

Generate a structure from string in POSCAR format.

Parameters:

elements (list[str]) – Name of the elements in the order they appear in the POSCAR file. If the elements are specified in the POSCAR file, this argument is optional and if set it will overwrite the choice in the POSCAR file. Old POSCAR files do not specify the name of the elements; in that case this argument is required.

classmethod from_ase(structure)¶

Generate a structure from the ase Atoms class.

lattice_vectors()¶

Return the lattice vectors spanning the unit cell

Returns:

Lattice vectors of the unit cell in Å.

Return type:

np.ndarray

number_atoms()¶

Return the total number of atoms in the structure.

number_steps()¶

Return the number of structures in the trajectory.

plot(*args, **kwargs)¶

Wrapper around to_view() method.

This method will visualize the quantity in the structure. Please refer to the to_view() method for a documentation of the allowed arguments.

Returns:

A visualization of the quantity within the crystal structure.

Return type:

View

positions()¶

Return the direct coordinates of all ions in the unit cell.

Direct or fractional coordinates measure the position of the ions in terms of the lattice vectors. Hence they are dimensionless quantities.

Returns:

Positions of all ions in terms of the lattice vectors.

Return type:

np.ndarray

print()¶

Print a string representation of this instance.

read(*args, **kwargs)¶

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

selections()¶

Returns possible alternatives for this particular quantity VASP can produce.

The returned dictionary contains a single item with the name of the quantity mapping to all possible selections. Each of these selection may be passed to other functions of this quantity to select which output of VASP is used.

Returns:

The key indicates this quantity and the values possible choices for arguments to other functions of this quantity.

Return type:

dict

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

to_ngl(*args, **kwargs)¶

Convert the view to an NGL widget.

This method wraps the to_view() method and converts the resulting View to an NGL widget. The to_view() method documents all the possible arguments of this function.

Returns:

A widget to display the structure and other quantities in the unit cell.

Return type:

NGLWidget

to_view(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:

View

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

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

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

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

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

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