Calculation ¶
Provide refinement functions for a the raw data of a VASP calculation run in any directory.
The calculation object always reads the VASP calculation from the current
working directory. This class gives you a more fine grained control so that you
can use a Python script or Jupyter notebook in a different folder or rename the
files that VASP produces.
To create a new instance, you should use the classmethod from_path() or
from_file() and not the constructor. This will ensure that the path to
your VASP calculation is properly set and all features work as intended.
The two methods allow you to read VASP results from a specific folder other
than the working directory or a nondefault file name.
With the Calculation instance, you can access the quantities VASP computes via
the attributes of the object. The attributes are the same provided by the
calculation object. You can find links to how to use these quantities
below.
Examples
Let’s first create some example data in a temporary directory. Please define path as the path to a temporary directory that does not exist yet. This command create example data in that directory and will return a Calculation but we ignore the result.
>>> _ = py4vasp.demo.calculation(path)
We can now, generate a new calculation object to access the data from this path
>>> calculation = Calculation.from_path(path)
Plot the density of states (DOS) of the calculation
>>> calculation.dos.plot()
Graph(series=[Series(x=array(...), y=array(...), label='total', ...)],
xlabel='Energy (eV)', ..., ylabel='DOS (1/eV)', ...)
Read the energies for a structure relaxation run into a Python dictionary
>>> calculation.energy[:].read()
{'free energy TOTEN': array(...), 'energy without entropy': array(...),
'energy(sigma->0)': array(...)}
Convert the structure to a POSCAR format
>>> poscar_string = calculation.structure.to_POSCAR()
from_file
str | pathlib.Path) → Calculation
Set up a Calculation from a particular file.
Typically this limits the amount of information, you have access to, so prefer
creating the instance with the from_path() if possible. Most data is
found in the vaspout.h5 file, so if you renamed it for backup purposes most
functions of py4vasp will work, when you pass it into this constructor.
Please keep in mind that creating a new Calculation will not read any data. You can create an instance for a specific file and create or modify it afterwards. py4vasp access the data in the moment when it is needed e.g. to generate a plot or read it to a dictionary. However, this also means that you need to make sure to keep track of any changes, because the Calculation object is always a representation of the current contents of the file not the ones at creation of the Calculation object.
Parameters
- file_name:
str | pathlib.Path - Name of the file from which the data is read.
Returns
Calculation- A calculation accessing the data in the given file.
Examples
Create a new Calculation object to the vaspout.h5 file. For the most parts this
is equivalent to the from_path() method so you should typically use that
instead.
>>> calculation = Calculation.from_file("vaspout.h5")
Sometime you rename the VASP output as a backup. Then the from_file constructor is your only option.
>>> calculation = Calculation.from_file("path/to/file/backup.h5")
from_path
str | pathlib.Path) → Calculation
Set up a Calculation for a particular path and so that all files are opened there.
py4vasp knows to which files the relevant information is written. It will automatically open the files as necessary and extract the required data from them. Then the raw data is refined according to the selected methods.
Importantly, the creation of the Calculation object does not require that the VASP calculation was already finished. It does not even need the path to exist. All data is lazily loaded at the moment when it is needed. This also means that if you change the data, e.g. by rerunning VASP in the same path, py4vasp will directly read the new results. If you want to keep the old results, please run the new calculation in a new path.
Parameters
- path_name:
str | pathlib.Path - Name of the path associated with the calculation.
Returns
Calculation- A calculation associated with the given path.
Examples
Create a new Calculation object from a specific path.
>>> calculation = Calculation.from_path("path/to/calculation")
You can also pass in pathlib Path objects or anything else that can be converted into it.
>>> calculation = Calculation.from_path(pathlib.Path.cwd())
path
Available quantities
band- The band structure contains the k point resolved eigenvalues.
bandgap- This class describes the band extrema during the relaxation or MD simulation.
born_effective_charge- The Born effective charge tensors couple electric field and atomic displacement.
current_density- Represents current density on the grid in the unit cell.
density- This class accesses various densities (charge, magnetization, …) of VASP.
dielectric_function- The dielectric function describes the material response to an electric field.
dielectric_tensor- The dielectric tensor is the static limit of the
dielectric function. dos- The density of states (DOS) describes the number of states per energy.
effective_coulomb- Effective Coulomb interaction U obtained with the constrained random phase approximation (cRPA).
elastic_modulus- The elastic modulus is the second derivative of the energy with respect to strain.
electron_phonon.bandgap- ElectronPhononBandgap provides access to the electron-phonon bandgap renormalization data and selection utilities.
electron_phonon.chemical_potential- Provides access to the electron-phonon chemical potential data calculated during an electron-phonon calculation.
electron_phonon.self_energy- Access and analyze electron-phonon self-energy data.
electron_phonon.transport- Provides access to electron-phonon transport data and selection utilities.
electronic_minimization- Access the convergence data for each electronic step.
energy- The energy data for one or several steps of a relaxation or MD simulation.
exciton.density- This class accesses exciton charge densities of VASP.
exciton.eigenvector- BSE can compute excitonic properties of materials.
force- The forces determine the path of the atoms in a trajectory.
force_constant- Force constants are the 2nd derivatives of the energy with respect to displacement.
internal_strain- The internal strain is the derivative of energy with respect to displacement and strain.
kpoint- The k-point mesh used in the VASP calculation.
local_moment- The local moments describe the charge and magnetization near an atom.
nics- This class accesses information on the nucleus-independent chemical shift (NICS).
pair_correlation- The pair-correlation function measures the distribution of atoms.
partial_density- Partial charges describe the fraction of the charge density in a certain energy, band, or k-point range.
phonon.band- The phonon band structure contains the q-resolved phonon eigenvalues.
phonon.dos- The phonon density of states (DOS) describes the number of modes per energy.
phonon.mode- Describes a collective vibration of atoms in a crystal.
piezoelectric_tensor- The piezoelectric tensor is the derivative of the energy with respect to strain and field.
polarization- The static polarization describes the electric dipole moment per unit volume.
potential- The local potential describes the interactions between electrons and ions.
projector- The projectors used for atom and orbital resolved quantities.
run_info- Contains information about the VASP run.
stress- The stress describes the force acting on the shape of the unit cell.
structure- The structure contains the unit cell and the position of all ions within.
system- The SYSTEM tag in the INCAR file is a title you choose for a VASP calculation.
velocity- The velocities describe the ionic motion during an MD simulation.
workfunction- The workfunction describes the energy required to remove an electron to the vacuum.