structure

py4vasp.calculation.structure

(*args, **kwargs)

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

Let us create some example data so that we can illustrate how to use this class. Of course you can also use your own VASP calculation data if you have it available.

>>> from py4vasp import demo
>>> calculation = demo.calculation(path)

If you access the structure, 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.

>>> calculation.structure.number_steps()
1

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

>>> calculation.structure[:].number_steps()
4

You can also select specific {step}s or a subset of {step}s as follows

>>> calculation.structure[3].number_steps()
1
>>> calculation.structure[1:4].number_steps()
3

A_to_nm

= 0.1
Converting Å to nm used for mdtraj trajectories.

cartesian_positions

() → np.ndarray

Convert the positions from direct coordinates to cartesian ones.

Returns

np.ndarray
Position of all atoms in cartesian coordinates in Å.

Examples

First, we create some example data so that we can illustrate how to use this method. You can also use your own VASP calculation data if you have it available.

>>> from py4vasp import demo
>>> calculation = demo.calculation(path)

If you use the cartesian_positions method, 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.

>>> calculation.structure.cartesian_positions()
array([[...]])

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

>>> calculation.structure[:].cartesian_positions()
array([[[...]]])

from_POSCAR

(

  • poscar,
  • elements: list[str] = None

)

Generate a structure from string in POSCAR format.

The POSCAR format is the standard format to represent crystal structures in VASP. This method allows to create a structure from a POSCAR string. To read more about the POSCAR format, please refer to the VASP manual.

Parameters

elements: list[str] = None
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.

Examples

We can create a GaAs structure from a POSCAR string as follows

>>> poscar = '''\
... GaAs
... 5.65325
... 0.0 0.5 0.5
... 0.5 0.0 0.5
... 0.5 0.5 0.0
... 1 1
... fractional
... 0.0 0.0 0.0
... 0.25 0.25 0.25'''
>>> structure = py4vasp.calculation.structure.from_POSCAR(poscar, elements=['Ga', 'As'])
>>> print(structure.to_POSCAR())
GaAs
5.6532...
0.0... 0.5... 0.5...
0.5... 0.0... 0.5...
0.5... 0.5... 0.0...
Ga As
1 1
Direct
0.00... 0.00... 0.00...
0.25... 0.25... 0.25...

from_ase

(structure)
Generate a structure from the ase Atoms class.

lattice_vectors

() → np.ndarray

Return the lattice vectors spanning the unit cell

Returns

np.ndarray
Lattice vectors of the unit cell in Å.

Examples

First, we create some example data so that we can illustrate how to use this method. You can also use your own VASP calculation data if you have it available.

>>> from py4vasp import demo
>>> calculation = demo.calculation(path)

If you use the lattice_vectors method, 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.

>>> calculation.structure.lattice_vectors()
array([[...], [...], [...]])

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

>>> calculation.structure[:].lattice_vectors()
array([[[...]], [[...]], [[...]], [[...]]])

number_atoms

()
Return the total number of atoms in the structure.

number_steps

()
Return the number of structures in the trajectory.

path

Returns the path from which the output is obtained.

plot

(*args, **kwargs) → View

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

View
A visualization of the quantity within the crystal structure.

positions

() → np.ndarray

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

np.ndarray
Positions of all ions in terms of the lattice vectors.

Examples

First, we create some example data so that we can illustrate how to use this method. You can also use your own VASP calculation data if you have it available.

>>> from py4vasp import demo
>>> calculation = demo.calculation(path)

If you use the positions method, 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.

>>> calculation.structure.positions()
array([[...]])

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

>>> calculation.structure[:].positions()
array([[[...]]])

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

() → dict

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. Some quantities provide additional elements which can be passed as selection for other routines.

Returns

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

to_POSCAR

(ion_types: Sequence = None) → str

Convert the structure(s) to a POSCAR format.

Use this method to generate a string in POSCAR format representing the structure(s). You can use this string to write a POSCAR file for VASP. This can be useful if you want to use the relaxed structure from a VASP calculation or a snapshot from an MD simulation as input for a new VASP calculation.

Parameters

ion_types: Sequence = None
Overwrite the ion types present in the raw data. You can use this to quickly generate different stoichiometries without modifying the underlying raw data.

Returns

str
Returns the POSCAR of the selected steps.

Examples

First, we create some example data so that we can illustrate how to use this method. You can also use your own VASP calculation data if you have it available.

>>> from py4vasp import demo
>>> calculation = demo.calculation(path)

If you use the to_POSCAR method, 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.

>>> poscar = calculation.structure.to_POSCAR()
>>> assert poscar == str(calculation.structure)

You can also select specific steps as follows

>>> poscar = calculation.structure[1].to_POSCAR()
>>> assert poscar == str(calculation.structure[1])

Notice that converting multiple steps to POSCAR format is not implemented.

to_ase

(

  • supercell: int | np.ndarray = None,
  • ion_types: Sequence = None

) → Atoms

Convert the structure to an ASE Atoms object.

ASE (the Atomic Simulation Environment) is a popular Python package for atomistic simulations. This method converts the VASP structure to an ASE Atoms object, which can be used for further analysis and visualization.

Parameters

supercell: int | np.ndarray = None
If present the structure is replicated the specified number of times along each direction.
ion_types: Sequence = None
Overwrite the ion types present in the raw data. You can use this to quickly generate different stoichiometries without modifying the underlying raw data.

Returns

Atoms
Structural information for ASE package. Read more about ASE here.

Examples

First, we create some example data so that we can illustrate how to use this method. You can also use your own VASP calculation data if you have it available.

>>> from py4vasp import demo
>>> calculation = demo.calculation(path)

If you use the to_ase method, 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.

>>> calculation.structure.to_ase()
Atoms(symbols='...', pbc=True, cell=[[...]])

You can also select specific steps as follows

>>> calculation.structure[1].to_ase()
Atoms(symbols='...', pbc=True, cell=[[...]])

Notice that converting multiple steps to ASE trajectories is not implemented.

You may also replicate the structure by specifying a supercell. If you compare the cell size with the previous example, you will see that it is doubled in all directions.

>>> calculation.structure.to_ase(supercell=2)
Atoms(symbols='...', pbc=True, cell=[[...]])

The supercell size can also be different for the different directions. The three lattice vectors will be scaled accordingly.

>>> calculation.structure.to_ase(supercell=[2,3,1])
Atoms(symbols='...', pbc=True, cell=[[...]])

to_dict

(ion_types: Sequence = None) → dict

Read the structural information into a dictionary.

The returned dictionary contains the following keys:

  • ‘lattice_vectors’: The lattice vectors of the unit cell.
  • ‘positions’: The positions of the atoms in the unit cell.
  • ‘elements’: The chemical elements of the atoms in the unit cell.
  • ‘names’: The names of the atoms in the unit cell.

Note that ‘elements’ and ‘names’ have the same length as the number of atoms in the unit cell.

Parameters

ion_types: Sequence = None
Overwrite the ion types present in the raw data. You can use this to quickly generate different stoichiometries without modifying the underlying raw data.

Returns

dict
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.

Examples

First, we create some example data so that we can illustrate how to use this method. You can also use your own VASP calculation data if you have it available.

>>> from py4vasp import demo
>>> calculation = demo.calculation(path)

If you use the to_dict method, 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.

>>> calculation.structure.to_dict()
{'lattice_vectors': array([[...]]), 'positions': array([[...]]),
    'elements': [...], 'names': [...]}

To select the results for all steps, you don’t specify the array boundaries. Notice that in this case the lattice vectors and positions contain an additional dimension for the different steps.

>>> calculation.structure[:].to_dict()
{'lattice_vectors': array([[[...]]]), 'positions': array([[[...]]]),
    'elements': [...], 'names': [...]}

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

>>> calculation.structure[1].to_dict()
{'lattice_vectors': array([[...]]), 'positions': array([[...]]),
    'elements': [...], 'names': [...]}
>>> calculation.structure[0:2].to_dict()
{'lattice_vectors': array([[[...]]]), 'positions': array([[[...]]]),
    'elements': [...], 'names': [...]}

to_lammps

(standard_form: bool = True) → str

Convert the structure to LAMMPS format.

LAMMPS is a popular molecular dynamics simulation software. This method converts the structure to a string in LAMMPS format, which can be used as input for LAMMPS simulations.

Parameters

standard_form: bool = True
Determines whether the structure is standardize, i.e., the lattice vectors are a triagonal matrix.

Returns

str
Returns a string describing the structure for LAMMPS

Examples

First, we create some example data so that we can illustrate how to use this method. You can also use your own VASP calculation data if you have it available.

>>> from py4vasp import demo
>>> calculation = demo.calculation(path)

If you use the to_lammps method, 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.

>>> print(calculation.structure.to_lammps())
Configuration 1: system "..."
... atoms
... atom types
... xlo xhi
... ylo yhi
... zlo zhi
... xy xz yz
Atoms # atomic
1 1 ...

You can also select specific steps as follows

>>> print(calculation.structure[1].to_lammps())
Configuration 1: system "..."
... atoms
... atom types
... xlo xhi
... ylo yhi
... zlo zhi
... xy xz yz
Atoms # atomic
1 1 ...

Notice that converting multiple steps to LAMMPS format is not implemented.

LAMMPS requires either a standard form of the unit cell or the transformation from the original cell to the standard form. By default, the standard form is used. You can disable this behavior as follows

>>> print(calculation.structure.to_lammps(standard_form=False))
Configuration 1: system "..."
... atoms
... atom types
... avec
... bvec
... cvec
... abc origin
Atoms # atomic
1 1 ...

to_mdtraj

(ion_types: Sequence = None) → mdtraj.Trajectory

Convert the trajectory to mdtraj.Trajectory

mdtraj is a popular Python package to analyze molecular dynamics trajectories. This method converts the VASP structure trajectory to an mdtraj.Trajectory object, which can be used for further analysis and visualization.

Parameters

ion_types: Sequence = None
Overwrite the ion types present in the raw data. You can use this to quickly generate different stoichiometries without modifying the underlying raw data.

Returns

mdtraj.Trajectory
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.

Examples

First, we create some example data so that we can illustrate how to use this method. You can also use your own VASP calculation data if you have it available.

>>> from py4vasp import demo
>>> calculation = demo.calculation(path)

To convert the whole trajectory (all steps), you don’t specify the array boundaries.

>>> calculation.structure[:].to_mdtraj()
<mdtraj.Trajectory with ... frames, ... atoms, ...>

You can also select a subset of steps as follows

>>> calculation.structure[0:2].to_mdtraj()
<mdtraj.Trajectory with 2 frames, ... atoms, ...>

You cannot convert a single structure to mdtraj.Trajectory.

to_ngl

(*args, **kwargs) → NGLWidget

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

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

to_vasp_viewer

(*args, **kwargs) → VASPViewerWidget

Convert the view to a VASP Viewer widget.

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

Returns

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

to_view

(

  • supercell: int | np.ndarray = None,
  • ion_types: Sequence = None

) → View

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

This method uses the View class to create a 3d visualization of the atomic structure(s) in the unit cell.

Parameters

supercell: int | np.ndarray = None
If present the structure is replicated the specified number of times along each direction.
ion_types: Sequence = None
Overwrite the ion types present in the raw data. You can use this to quickly generate different stoichiometries without modifying the underlying raw data.

Returns

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

Examples

First, we create some example data so that we can illustrate how to use this method. You can also use your own VASP calculation data if you have it available.

>>> from py4vasp import demo
>>> calculation = demo.calculation(path)

If you use the to_view method, 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.

>>> calculation.structure.to_view()
View(elements=array([[...]], dtype=...), lattice_vectors=array([[[...]]]),
    positions=array([[[...]]]), ...)

To select the results for all steps, you don’t specify the array boundaries. Notice that in this case the lattice vectors and positions contain an additional dimension for the different steps.

>>> calculation.structure[:].to_view()
View(elements=array([[...], ..., [...]], dtype=...), lattice_vectors=array([[[...]], ..., [[...]]]),
    positions=array([[[...]], ..., [[...]]]), ...)

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

>>> calculation.structure[1].to_view()
View(elements=array([[...]], dtype=...), lattice_vectors=array([[[...]]]),
    positions=array([[[...]]]), ...)
>>> calculation.structure[0:2].to_view()
View(elements=array([[...], [...]], dtype=...), lattice_vectors=array([[[...]], [[...]]]),
    positions=array([[[...]], [[...]]]), ...)

You may also replicate the structure by specifying a supercell.

>>> calculation.structure.to_view(supercell=2)
View(..., supercell=array([2, 2, 2]), ...)

The supercell size can also be different for the different directions.

>>> calculation.structure.to_view(supercell=[2,3,1])
View(..., supercell=array([2, 3, 1]), ...)

volume

() → float or np.ndarray

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

Returns

float or np.ndarray
The volume(s) of the selected step(s) in ų.

Examples

First, we create some example data so that we can illustrate how to use this method. You can also use your own VASP calculation data if you have it available.

>>> from py4vasp import demo
>>> calculation = demo.calculation(path)

If you use the volume method, 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.

>>> calculation.structure.volume()
np.float...

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

>>> calculation.structure[:].volume()
array([...])