Support functions

Helper functions

class storq.vasp.helpers.Helpers

archive(tag=None, organize=True, cleanup=False)

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

backup(files='minimal', backup_dir='run.')

Flexible function for backing up calcualtion files.

Parameters:

files (str, list) – Can be ‘minimal’ or ‘all’ in which case a minimal set of files or all files are backed up, respectively. Can also be a list of filenames to back up.

copy_files(dir_new, files='all', exceptions=None)

remove_files(files, exceptions=None)

suggest_encut(factor=1.3)

Heuristic for setting the PW cutoff.

Uses the formula factor*max(ENMAX) where the maximum is taken over all POTCARs involved.

Parameters:

factor (float) – Multiplicative scaling factor for the eneryg cutoff.

suggest_num_bands(factor=1.0)

Convenience function to compute and set the number of bands.

Uses the same rule as VASP does internally, which looks roughly like

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

The difference is that this method allows the specification of a scaling factor for the term proportional to the number of ions. This can be useful for e.g., transition metals where more bands need to be added sometimes (factor=2 can be required).

Parameters:

factor (float) – Multiplicative scaling factor for the number of bands.

Returns:

The new number of bands.

Return type:

int

storq.vasp.helpers.copy_files(dir_old, dir_new, files='all', exceptions=None)

Flexible method for copying files.

storq.vasp.helpers.remove_files(directory, files, exceptions=None)

Flexible function for removing calculation files.

Note that this is a staticmethod so as to enable cleanup of broken calculation directories where a calculator object cannot be intialized.

Parameters:

• directory (str) – The calculation directory from which to remove files.

• files (Union[str, list]) – Decides which files to remove. Can be ‘input’, ‘output’, ‘all’, ‘backup’, ‘dir’, the name of a single file, or a list of filenames.

• exceptions (Union[str, list, set]) – Exceptions that will not be removed.

Getters

class storq.vasp.getters.Getters

get_ados(atom_index, orbital, spin=1, efermi=None)

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

Parameters:

• atom_index (int) – pass

• orbital (string) – can be any of ‘s’, ‘p’, ‘d’

• spin (int) – pass

• efermi (float) – the fermi energy

Returns:

• energies (np.ndarray) – pass

• ados (np.ndarray) – pass

get_charge_density(spin=0, filename=None)

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

Supported file formats: CHG, CHGCAR

Parameters:

spin (int) – pass

Returns:

x, y, z – charge density arrays

Return type:

np.ndarrays

get_charges(atoms=None)

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

get_composition(basis=None)

Acquire the chemical composition of an atoms object

Returns:

atoms and their compositions dictionary sorted by atomic number

Return type:

dict

Parameters:

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

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

get_density_of_states(index=-1)

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

Parameters:

• f (fileobj) – input file

• index (int) – index of frame(s) to return

Returns:

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

Return type:

generator

get_dipole_moment(atoms=None)

Return dipole_moment.

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

get_dipole_vector()

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

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

get_eigenvalues(kpt=0, spin=0)

Return array of eigenvalues for kpt and spin.

get_elapsed_time()

Return elapsed calculation time in seconds from the OUTCAR file.

get_elastic_moduli()

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.

get_electron_density_center(spin=0, scaled=True)

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

get_elf()

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

get_fermi_level()

Method that reads Fermi energy from OUTCAR file

get_homo_lumo()

Calculate VBM and CBM.

get_ibz_k_points(cartesian=True)

Return the IBZ k-point list.

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

get_k_point_weights()

Return the k-point weights.

get_linear_response_properties()

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

get_local_potential()

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.

get_memory()

Retrieves the recommended memory from the OUTCAR in GB.

get_num_bands()

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

Get the number of ionic steps from the OUTCAR file.

Returns:

The number of ionic steps.

Return type:

int

get_num_spins()

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

get_num_valence()

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

get_num_valence_potcar(filename=None)

Get the default number of valence electrons.

Parameters:

filename (str) – name of the POTCAR file in which to look

Returns:

number of electorns for each species in filename

Return type:

list

get_occupation_numbers(kpt=0, spin=0)

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.

get_orbital_occupations()

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.

get_potcars()

get_program_info()

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

get_volumetric_data(filename=None, **kwargs)

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

Validation functions

storq.vasp.validate.addgrid(calc, val)

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

storq.vasp.validate.aggac(calc, val)

Fraction of gradient correction to correlation in a hybrid calculation

storq.vasp.validate.algo(calc, val)

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

http://cms.mpi.univie.ac.at/wiki/index.php/ALGO

storq.vasp.validate.amin(calc, val)

Initial value of the linear mixing parameter.

storq.vasp.validate.amix(calc, val)

Linear mixing parameter.

storq.vasp.validate.atoms(calc, val)

The Atoms object. (ase.atoms.Atoms).

storq.vasp.validate.bmix(calc, val)

Controls deviation from linear mixing.

storq.vasp.validate.dipol(calc, val)

Specifies the center of the cell used for the calculation of the dipole moment.

storq.vasp.validate.eb_k(calc, val)

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

https://github.com/henniggroup/VASPsol/blob/master/docs/USAGE.md

storq.vasp.validate.ediff(calc, val)

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

http://cms.mpi.univie.ac.at/wiki/index.php/EDIFF

storq.vasp.validate.ediffg(calc, val)

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

If EDIFFG < 0, it defines a force criteria.

http://cms.mpi.univie.ac.at/wiki/index.php/EDIFFG

storq.vasp.validate.encut(calc, val)

Planewave cutoff in eV. (float)

http://cms.mpi.univie.ac.at/wiki/index.php/ENCUT

storq.vasp.validate.gga(calc, val)

Grants access to certain special GGAs

storq.vasp.validate.ialgo(calc, val)

IALGO selects the algorithm used to optimize the orbitals.

storq.vasp.validate.ibrion(calc, val)

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

storq.vasp.validate.icharg(calc, val)

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.idipol(calc, val)

Turns dipole corrections for total energy on along specified axis.

storq.vasp.validate.images(calc, val)

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)

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)

ISMEAR determines how the partial occupancies are set.

Parameters:

val (int) – new value

storq.vasp.validate.ispin(calc, val)

Control spin-polarization.

Value	Meaning
1	default, no spin polarization
2	spin-polarization.

Parameters:

val (int) – new value

storq.vasp.validate.istart(calc, val)

Controls the restarting behaviour of VASP.

storq.vasp.validate.isym(calc, val)

ISYM determines the way VASP treats symmetry.

http://cms.mpi.univie.ac.at/wiki/index.php/ISYM

storq.vasp.validate.ivdw(calc, val)

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

storq.vasp.validate.keyword_alist()

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

Returns the alist for use in Emacs.

storq.vasp.validate.keywords()

Return list of keywords we vasp_validate.

Returns a lisp list for Emacs.

storq.vasp.validate.kgamma(calc, val)

Determines whether the grid is Gamma- or Monkhorst-Pack if the kspacing tag was used.

Parameters:

val (bool) – new value

storq.vasp.validate.kpar(calc, val)

Control parallelization over k-points

storq.vasp.validate.kpts(calc, val)

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

storq.vasp.validate.kspacing(calc, val)

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)

LCHARG determines whether CHGCAR and CHG are written.

Parameters:

val (bool) – new value

storq.vasp.validate.ldau(calc, val)

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

Parameters:

val (bool) – new value

storq.vasp.validate.ldau_luj(calc, val)

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)

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)

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.ldipol(calc, val)

Turns dipole corrections on for potential and forces.

storq.vasp.validate.lmaxmix(calc, val)

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)

Determines whether the PROCAR or PROOUT files are written.

Parameters:

val (int) – new value

storq.vasp.validate.lreal(calc, val)

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)

LSOL determines whether the VASPsol is activated.

Parameters:

val (bool) – new value

storq.vasp.validate.luse_vdw(calc, val)

luse_vdw turns on vdW-DF by Langreth and Lundqvist

storq.vasp.validate.lvhar(calc, val)

If True only the electrostatic part of the local potential is written.

storq.vasp.validate.lvtot(calc, val)

Controls whether the local potential is written.

storq.vasp.validate.lwave(calc, val)

LWAVE determines whether the WAVECAR is written.

Parameters:

val (bool) – new value

storq.vasp.validate.magmom(calc: <module 'ase.calculators.calculator' from '/usr/local/lib/python3.10/dist-packages/ase/calculators/calculator.py'>, val: ~typing.List[int] | ~numpy.ndarray)

MAGMOM specifies the initial magnetic moment for each atom.

Raises:

• TypeError – if the input value is neither a list nor a numpy array

• ValueError – if the length of the input list does not match the number of atoms of the structure associated with the calculator

storq.vasp.validate.maxmix(calc, val)

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

Parameters:

val (int) – new value

storq.vasp.validate.nbands(calc, val)

NBANDS determines the actual number of bands in the calculation.

Parameters:

val (int) – new value

storq.vasp.validate.ncore(calc, val)

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

Parameters:

val (int) – new value

storq.vasp.validate.nelm(calc, val)

Maximum number of allowed iterations in the SCF-cycle.

storq.vasp.validate.nelmdl(calc, val)

Number of non-SCF steps.

storq.vasp.validate.nelmin(calc, val)

Minimum number of iterations in the SCF-cycle.

storq.vasp.validate.npar(calc, val)

Determines how many bands are run in parallel

storq.vasp.validate.nsim(calc, val)

Sets block size for the RMM-DIIS algorithm

storq.vasp.validate.nsw(calc, val)

NSW sets the maximum number of ionic steps.

Parameters:

val (int) – new value

storq.vasp.validate.nupdown(calc, val)

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)

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

Parameters:

val (float) – new value

storq.vasp.validate.pp(calc, val)

Determines where POTCARS are retrieved from.

Parameters:

val (string) – new value

storq.vasp.validate.prec(calc, val)

Specifies the precision vasp_mode.

Parameters:

val (string) – new value

storq.vasp.validate.rwigs(calc, val)

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

in vasp.py you enter a dictionary of::

{sym: radius}

Parameters:

val (list) – new value

storq.vasp.validate.setups(calc, val)

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)

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

storq.vasp.validate.spring(calc, val)

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

http://cms.mpi.univie.ac.at/wiki/index.php/SPRING

storq.vasp.validate.symprec(calc, val)

Controls symmetry-detection precision.

storq.vasp.validate.xc(calc, val)

Set exchange-correlation functional. (string)

Structure relaxation

class storq.vasp.relaxer.Relaxer

relax(max_runs=10, backup=None, switch_opt=False, switch_tol_favg=None, switch_tol_fmax=None)

Succesively run vasp until convergence.

Parameters:

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

• switch_opt (bool) – Toggle automatic switching from conjugate gradeint (ibrion=2) to quasi-newton (ibrion=1).

• switch_tol_favg (float) – Average force threshold below which quasi-newton is switched on.

• switch_tol_fmax (float) – Maximum force threshold below which quasi-newton is switched on.