Support functions

Helper functions

class storq.vasp.helpers.Helpers[source]
archive(tag=None, organize=True, cleanup=False)[source]

Archive a run by (separately) gzipping entire vaspdir, vasp xml file and OUTCAR.

backup(include='minimal', dirname='run.')[source]

Backup VASP input/output files in a folder.

static remove(target, exceptions=set())[source]

Versatile method for removing certain files.

POTCAR support functions


Return ENMAX from the potcar file.


Return ENMIN from the potcar file.


Return the ZVAL for a potcar file.

parse this line:
POMASS = 106.420; ZVAL = 10.000 mass and valenz


class storq.vasp.getters.Getters[source]
get_ados(*args, **kwargs)

Return Atom projected DOS for atom index, orbital and spin.

orbital: string [‘s’, ‘p’, ‘d’]

If efermi is not None, use this value as 0.0.

Returns:(energies, ados)

Wrapped in vasp.tryit.

get_charge_density(*args, **kwargs)

Returns x, y, and z coordinate and charge density arrays.

Supported file formats: CHG, CHGCAR :param int spin: an integer :returns: x, y, z, charge density arrays :rtype: 3-d numpy arrays Relies on ase.calculators.VaspChargeDensity().

Wrapped in vasp.tryit.


Returns a list of cached charges from a previous call to bader(). Useful for storing the charges to a database.


Acquire the chemical composition of an atoms object

Returns: a dictionary of atoms and their compositions dictionary sorted by atomic number

basis: string allows the user to define the basis element for determining the composition. If a basis element is specified, the composition of that element is returned.

get_core_levels(*args, **kwargs)

Parse an OUTCAR file and extract either the average (electrostatic) potential at core or the core state eigenenergies.

Parameters:f (fileobj) – input file
Returns:the list is either comprised of floats representing the average electrostatic vasp_potentials at the ionic cores or dictionaries containing the Kohn-Sham eigen energies of the core states; if neither information is found the method returns a None value
Return type:list

Wrapped in vasp.tryit.

get_db(*args, **kwargs)

Retrieve values for each key in keys.

First look for key/value, then in data.

Wrapped in vasp.tryit.


Return the default electrons for each species.

get_density_of_states(*args, **kwargs)

Parse vasprun.xml file and extract the density of states.

  • f (fileobj) – input file
  • index (int) – index of frame(s) to return

dictionary, each entry of corresponds to another spin channel and comprises a tuple of two lists (energies and density of states)

Return type:


Wrapped in vasp.tryit.

get_dipole_moment(*args, **kwargs)

Return dipole_moment.

dipole_moment = ((dipole_vector**2).sum())**0.5/Debye

Wrapped in vasp.tryit.

get_dipole_vector(*args, **kwargs)

Tries to return the dipole vector of the unit cell in atomic units.

Returns None when CHG file is empty/not-present.

Wrapped in vasp.tryit.

get_eigenvalues(*args, **kwargs)

Return array of eigenvalues for kpt and spin.

Wrapped in vasp.tryit.

get_elapsed_time(*args, **kwargs)

Return elapsed calculation time in seconds from the OUTCAR file.

Wrapped in vasp.tryit.

get_elastic_moduli(*args, **kwargs)

Returns the total elastic moduli in GPa.

(i.e. the rigid ion and contributions from relaxation) from the OUTCAR file.

you must run with IBRION=6 and ISIF>= 3 for this output to exist.

There are also contributions from ionic relaxation ELASTIC MODULI CONTR FROM IONIC RELAXATION (kBar) and the rigid moduli SYMMETRIZED ELASTIC MODULI (kBar)

For now these are not returned.

Wrapped in vasp.tryit.

get_electron_density_center(*args, **kwargs)

Returns center of electron density. If scaled, use scaled coordinates, otherwise use cartesian coordinates.

Wrapped in vasp.tryit.


Returns x, y, z and electron localization function arrays.

get_fermi_level(*args, **kwargs)

Return the Fermi level.

Wrapped in vasp.tryit.

get_homo_lumo(*args, **kwargs)

Calculate VBM and CBM.

Wrapped in vasp.tryit.

get_ibz_k_points(*args, **kwargs)

Return the IBZ k-point list.

Uses vasprun.xml and returns them in cartesian coordinates. set cartesian=False to get them in reciprocal coordinates.

Wrapped in vasp.tryit.

get_k_point_weights(*args, **kwargs)

Return the k-point weights.

Wrapped in vasp.tryit.

get_linear_response_properties(*args, **kwargs)

Parse an OUTCAR file and extract properties that are obtained from linear response calculations. This includes elastic and dielectric tensors, Born effective charges as well as normal vasp_modes.

Parameters:f (fileobj) – input file
Returns:The properties are returned in the form of a dictionary, which contains entries for all properties that were succesfully parsed from the input file.
Return type:dictionary

Wrapped in vasp.tryit.

get_local_potential(*args, **kwargs)

Returns x, y, z, and local potential arrays

We multiply the data by the volume because we are reusing the charge density code which divides by volume.

Wrapped in vasp.tryit.


Retrieves the recommended memory from the OUTCAR in GB.

If no OUTCAR exists, or the memory estimate can not be found, return None


Return the number of bands.

NBANDS is read from an OUTCAR if it exists, otherwise the default value used by vasp is computed and returned.

get_number_of_ionic_steps(*args, **kwargs)

Get the number of ionic steps from the OUTCAR file.

Returns:The number of ionic steps.
Return type:int

Wrapped in vasp.tryit.


Returns number of spins. 1 if not spin-polarized 2 if spin-polarized

get_occupation_numbers(*args, **kwargs)

Read occupation_numbers for KPT and spin.

Read from vasprun.xml. This may be fractional occupation. For non-spin-polarized calculations you may need to multiply by 2.

Returns an np.array.

Wrapped in vasp.tryit.

get_orbital_occupations(*args, **kwargs)

Read occuations from OUTCAR.

Returns a numpy array of [[s, p, d tot]] for each atom.

You probably need to have used LORBIT=11 for this function to work.

Wrapped in vasp.tryit.


Return data about the vasp that was used for the calculation.


Return list of (symbol, path, date) for each POTCAR.


Return the number of valence electrons for the atoms. Calculated from the POTCAR file.

get_volumetric_data(*args, **kwargs)

Read filename to read the volumetric data in it. Supported filenames are CHG, CHGCAR, and LOCPOT.

Wrapped in vasp.tryit.


Setter functions for the Vasp calculator.

These are special keyword setters that are needed because a special tag represents some set of keywords, e.g. the xc tag, or a change implies multiple changes.

The general strategy is to construct a dictionary of the changes that is passed back to the set function.

class storq.vasp.setters.Setters[source]

Set parameters with keyword=value pairs.


A few special kwargs are handled separately to expand them prior to setting the parameters. This is done to enable one set to track changes.


Heuristic for setting the PW cutoff, uses the formula factor*max(ENMAX) where the maximum is taken over all POTCARs involved.


Returns dictionary of changes for ispin change.


Set the kpts dict.


Set the ldau_luj parameters.


Convenience function to automatically compute nbands for non-spin-polarized calculations using a rule which looks approximately like

nbands = int(nelectrons/2 + nions*factor)

this formula is suggested at for transition metals factor may be as high as 2.


Return rwigs parameters.


Set xc parameter.

Adds all the xc_defaults flags for the chosen xc.

Validation functions

Validation functions for Vasp keywords.

Each function should have the signature func(calc, val) and it should use exceptions or assertions to vasp_validate. Each function should have a brief docstring. The first line will be used as a tooltip in Emacs. An Emacs command will give access to the full docstring. It is encouraged to put URLs to full documentation, as they will be clickable in Emacs.

storq.vasp.validate.addgrid(calc, val)[source]

ADDGRID gives an extra grid for the evaluation of augmentation charges.

storq.vasp.validate.aggac(calc, val)[source]

Fraction of gradient correction to correlation in a hybrid calculation

storq.vasp.validate.algo(calc, val)[source]

specify the electronic minimisation algorithm (as of VASP.4.5) (string)

storq.vasp.validate.atoms(calc, val)[source]

The Atoms object. (ase.atoms.Atoms or a list of them for an NEB).

storq.vasp.validate.eb_k(calc, val)[source]

The relative permittivity of the solvent used in the VASPsol code. (float)

storq.vasp.validate.ediff(calc, val)[source]

EDIFF specifies the global break condition for the electronic loop. (float)

storq.vasp.validate.ediffg(calc, val)[source]

EDIFFG defines the break condition for the ionic relaxation loop. (float)

If EDIFFG < 0, it defines a force criteria.

storq.vasp.validate.encut(calc, val)[source]

Planewave cutoff in eV. (float)

storq.vasp.validate.gga(calc, val)[source]

Grants access to certain special GGAs

storq.vasp.validate.ialgo(calc, val)[source]

IALGO selects the algorithm used to optimize the orbitals.

storq.vasp.validate.ibrion(calc, val)[source]

IBRION determines the algorithm to update geometry during relaxtion. (int)

storq.vasp.validate.icharg(calc, val)[source]

Determines how VASP constructs the initial charge density.

Value Meaning
0 calculate from initial wave functions
1 read from the CHGCAR
2 (default) Superposition of atomic charge densities
11 for band-structure plots
Parameters:val (int) – new value
storq.vasp.validate.images(calc, val)[source]

The number of images for a nudge elastic band (NEB) calculation not counting the end points.

Parameters:val (int) – new value
storq.vasp.validate.isif(calc, val)[source]

ISIF determines what is changed during relaxations.

ISIF calculate force calculate stress tensor relax ions change cell shape change cell volume
0 yes no yes no no
1 yes trace only yes no no
2 yes yes yes no no
3 yes yes yes yes yes
4 yes yes yes yes no
5 yes yes no yes no
6 yes yes no yes yes
7 yes yes no no yes
Parameters:val (int) – new value
storq.vasp.validate.ismear(calc, val)[source]

ISMEAR determines how the partial occupancies are set.

Parameters:val (int) – new value
storq.vasp.validate.ispin(calc, val)[source]

Control spin-polarization.

Value Meaning
1 default, no spin polarization
2 spin-polarization.
Parameters:val (int) – new value
storq.vasp.validate.isym(calc, val)[source]

ISYM determines the way VASP treats symmetry.

storq.vasp.validate.ivdw(calc, val)[source]

IVDW determines the approximate vdW correction methods used.

Value Meaning
0 no correction
1|10 DFT-D2 method of Grimme (available as of VASP.5.2.11)
11 zero damping DFT-D3 method of Grimme (available as of VASP.5.3.4)
12 DFT-D3 method with Becke-Jonson damping (available as of VASP.5.3.4)
2 Tkatchenko-Scheffler method (available as of VASP.5.3.3)
21 Tkatchenko-Scheffler method with iterative Hirshfeld partitioning (available as of VASP.5.3.5)
202 Many-body dispersion energy method (MBD@rSC) (available as of VASP.5.4.1)
4 dDsC dispersion correction method (available as of VASP.5.4.1)
Parameters:val (int) – new value

Returns an alist of (keyword . “first doc string”).

Returns the alist for use in Emacs.


Return list of keywords we vasp_validate.

Returns a lisp list for Emacs.

storq.vasp.validate.kpar(calc, val)[source]

Control parallelization over k-points

storq.vasp.validate.kpts(calc, val)[source]

Sets k-points. Not a Vasp keyword. (list or dict)

storq.vasp.validate.kspacing(calc, val)[source]

KSPACING determines the number of k-points if the KPOINTS file is not present.

Parameters:val (float) – new value
storq.vasp.validate.lcharg(calc, val)[source]

LCHARG determines whether CHGCAR and CHG are written.

Parameters:val (bool) – new value
storq.vasp.validate.ldau(calc, val)[source]

LDAU switches on the L(S)DA+U.

Parameters:val (bool) – new value
storq.vasp.validate.ldau_luj(calc, val)[source]

Dictionary of DFT+U parameters:

ldau_luj={'Mn': {'L':  2, 'U': 0.0, 'J': 0.0},
          'O':  {'L': -1, 'U': 0.0, 'J': 0.0}},
storq.vasp.validate.ldauprint(calc, val)[source]

LDAUPRINT controls the verbosity of the L(S)DA+U routines.

Value Meaning
0 silent.
1 Write occupancy matrix to the OUTCAR file.
2 same as LDAUPRINT=1, plus potential matrix dumped to vasp_stdout
Parameters:val (int) – new value
storq.vasp.validate.ldautype(calc, val)[source]

LDAUTYPE specifies which type of L(S)DA+U approach will be used.

LDAUTYPE=1: Rotationally invariant LSDA+U [1]

LDAUTYPE=2: Simplified (rotationally invariant) LSDA+U [2]

  1. A. I. Liechtenstein, V. I. Anisimov and J. Zaane, Phys. Rev. B 52, R5467 (1995).
  2. S. L. Dudarev, G. A. Botton, S. Y. Savrasov, C. J. Humphreys and A. P. Sutton, Phys. Rev. B 57, 1505 (1998).
Parameters:val (int) – new value
storq.vasp.validate.lmaxmix(calc, val)[source]

LMAXMIX the max l-quantum number the charge densities used.

Mostly used for DFT+U. 4 for d-electrons (or 6 for f-elements)

Parameters:val (int) – new value
storq.vasp.validate.lorbit(calc, val)[source]

Determines whether the PROCAR or PROOUT files are written.

Parameters:val (int) – new value
storq.vasp.validate.lreal(calc, val)[source]

LREAL determines whether the projection operators are evaluated in real-space or in reciprocal space.

Parameters:val (bool/string) – new value
storq.vasp.validate.lsol(calc, val)[source]

LSOL determines whether the VASPsol is activated.

Parameters:val (bool) – new value
storq.vasp.validate.luse_vdw(calc, val)[source]

luse_vdw turns on vdW-DF by Langreth and Lundqvist

storq.vasp.validate.lwave(calc, val)[source]

LWAVE determines whether the WAVECAR is written.

Parameters:val (bool) – new value
storq.vasp.validate.magmom(calc, val)[source]

MAGMOM specifies the initial magnetic moment for each atom.

Parameters:val (list) – new value
storq.vasp.validate.maxmix(calc, val)[source]

MAXMIX specifies the maximum number steps stored in Broyden mixer (IMIX=4).

Parameters:val (int) – new value
storq.vasp.validate.nbands(calc, val)[source]

NBANDS determines the actual number of bands in the calculation.

Parameters:val (int) – new value
storq.vasp.validate.ncore(calc, val)[source]

NCORE determines the number of compute cores that work on an individual orbital.

Parameters:val (int) – new value
storq.vasp.validate.nelm(calc, val)[source]

NELM sets the maximum number of electronic SC (selfconsistency) steps which may be performed.

Parameters:val (int) – new value
storq.vasp.validate.npar(calc, val)[source]

Determines how many bands are run in parallel

storq.vasp.validate.nsim(calc, val)[source]

Sets block size for the RMM-DIIS algorithm

storq.vasp.validate.nsw(calc, val)[source]

NSW sets the maximum number of ionic steps.

Parameters:val (int) – new value
storq.vasp.validate.nupdown(calc, val)[source]

NUPDOWN sets the difference between the number of spin up and down electrons.

This fixes the bulk magnetic moment. The VASP manual specifies this should be an integer, but it appears floats work too.

Parameters:val (int/float) – new value
storq.vasp.validate.potim(calc, val)[source]

POTIM sets the time step (MD) or step width scaling (ionic relaxations).

Parameters:val (float) – new value
storq.vasp.validate.pp(calc, val)[source]

Determines where POTCARS are retrieved from.

Parameters:val (string) – new value
storq.vasp.validate.prec(calc, val)[source]

Specifies the precision vasp_mode.

Parameters:val (string) – new value
storq.vasp.validate.rwigs(calc, val)[source]

RWIGS specifies the Wigner-Seitz radius for each atom type.

in you enter a dictionary of::
{sym: radius}
Parameters:val (list) – new value
storq.vasp.validate.setups(calc, val)[source]

Sets up special setups for the POTCARS (list of (symbol/int, suffix)).

The first element of each pair of the list is either an integer index of the atom for the special setup, or a chemical symbol for all atoms of that type. The second element of the pair is a suffix to be appended to the symbol. For example, to use the O_s potcar set setups to: [[‘O’, ‘_s’]].

This is not a vasp keyword.

storq.vasp.validate.sigma(calc, val)[source]

SIGMA determines the width of the smearing in eV. (float)

storq.vasp.validate.spring(calc, val)[source]

The Spring constant in the elastic band method. -5 = NEB.

storq.vasp.validate.xc(calc, val)[source]

Set exchange-correlation functional. (string)

Structure relaxation

class storq.vasp.relaxer.Relaxer[source]
relax(*args, **kwargs)

Succesively run vasp until convergence.

  • atoms (Atoms) – Required by the ASE Calculator interface
  • properties (list) – Required by the ASE Calculator interface
  • system_changes (TODO) – Required by the ASE Calculator interface
  • max_runs (int) – Maximum number of vasp restarts allowed.
  • backup (list, str) – Determines which files are backed-up during successive runs. Can be all, minimal or a list of files to backup.

Wrapped in vasp.tryit.