pymatgen.io.vasp package

Submodules

pymatgen.io.vasp.help module

Get help with VASP parameters from VASP wiki.

class VaspDoc[source]

Bases: object

A VASP documentation helper.

Init for VaspDoc.

classmethod get_help(tag, fmt='text')[source]

Get help on a VASP tag.

Parameters:

tag (str) – VASP tag, e.g., ISYM.

Returns:

Help text.

classmethod get_incar_tags()[source]

Returns: All incar tags.

print_help(tag)[source]

Print the help for a TAG.

Parameters:

tag (str) – Tag used in VASP.

print_jupyter_help(tag)[source]

Display HTML help in ipython notebook.

Parameters:

tag (str) – Tag used in VASP.

pymatgen.io.vasp.inputs module

Classes for reading/manipulating/writing VASP input files. All major VASP input files.

exception BadIncarWarning[source]

Bases: UserWarning

Warning class for bad Incar parameters.

class Incar(params: dict[str, Any] | None = None)[source]

Bases: dict, MSONable

INCAR object for reading and writing INCAR files. Essentially consists of a dictionary with some helper functions.

Creates an Incar object.

Parameters:

params (dict) – A set of input parameters as a dictionary.

as_dict() → dict[source]

Returns:

MSONable dict.

check_params()[source]

Raises a warning for nonsensical or non-existent INCAR tags and parameters. If a keyword doesn’t exist (e.g. there’s a typo in a keyword), your calculation will still run, however VASP will ignore the parameter without letting you know, hence why we have this Incar method.

diff(other: Incar) → dict[str, dict[str, Any]][source]

Diff function for Incar. Compares two Incars and indicates which parameters are the same and which are not. Useful for checking whether two runs were done using the same parameters.

Parameters:

other (Incar) – The other Incar object to compare to.

Returns:

{“Same” : parameters_that_are_the_same, “Different”: parameters_that_are_different} Note that the parameters are return as full dictionaries of values. E.g. {“ISIF”:3}

Return type:

Dict of the following format

classmethod from_dict(d) → Incar[source]

Parameters:

d – Dict representation.

Returns:

Incar

static from_file(filename: PathLike) → Incar[source]

Reads an Incar object from a file.

Parameters:

filename (str) – Filename for file

Returns:

Incar object

static from_str(string: str) → Incar[source]

Reads an Incar object from a string.

Parameters:

string (str) – Incar string

Returns:

Incar object

classmethod from_string(*args, **kwds)[source]

from_string is deprecated! Use from_str instead

get_string(sort_keys: bool = False, pretty: bool = False) → str[source]

Returns a string representation of the INCAR. The reason why this method is different from the __str__ method is to provide options for pretty printing.

Parameters:

• sort_keys (bool) – Set to True to sort the INCAR parameters alphabetically. Defaults to False.

• pretty (bool) – Set to True for pretty aligned output. Defaults to False.

static proc_val(key: str, val: Any)[source]

Static helper method to convert INCAR parameters to proper types, e.g., integers, floats, lists, etc.

Parameters:

• key – INCAR parameter key

• val – Actual value of INCAR parameter.

write_file(filename: PathLike)[source]

Write Incar to a file.

Parameters:

filename (str) – filename to write to.

class Kpoints(comment: str = 'Default gamma', num_kpts: int = 0, style: KpointsSupportedModes = KpointsSupportedModes.Gamma, kpts: Sequence[float | int | Sequence] = ((1, 1, 1),), kpts_shift: Vector3D = (0, 0, 0), kpts_weights=None, coord_type=None, labels=None, tet_number: int = 0, tet_weight: float = 0, tet_connections=None)[source]

Bases: MSONable

KPOINT reader/writer.

Highly flexible constructor for Kpoints object. The flexibility comes at the cost of usability and in general, it is recommended that you use the default constructor only if you know exactly what you are doing and requires the flexibility. For most usage cases, the three automatic schemes can be constructed far more easily using the convenience static constructors (automatic, gamma_automatic, monkhorst_automatic) and it is recommended that you use those.

Parameters:

• comment (str) – String comment for Kpoints. Defaults to “Default gamma”.

• num_kpts – Following VASP method of defining the KPOINTS file, this parameter is the number of kpoints specified. If set to 0 (or negative), VASP automatically generates the KPOINTS.

• style – Style for generating KPOINTS. Use one of the Kpoints.supported_modes enum types.

• kpts (2D array) – 2D array of kpoints. Even when only a single specification is required, e.g. in the automatic scheme, the kpts should still be specified as a 2D array. e.g., [[20]] or [[2,2,2]].

• kpts_shift (3x1 array) – Shift for Kpoints.

• kpts_weights – Optional weights for kpoints. Weights should be integers. For explicit kpoints.

• coord_type – In line-mode, this variable specifies whether the Kpoints were given in Cartesian or Reciprocal coordinates.

• labels – In line-mode, this should provide a list of labels for each kpt. It is optional in explicit kpoint mode as comments for k-points.

• tet_number – For explicit kpoints, specifies the number of tetrahedrons for the tetrahedron method.

• tet_weight – For explicit kpoints, specifies the weight for each tetrahedron for the tetrahedron method.

• tet_connections – For explicit kpoints, specifies the connections of the tetrahedrons for the tetrahedron method. Format is a list of tuples, [ (sym_weight, [tet_vertices]), …]

The default behavior of the constructor is for a Gamma centered, 1x1x1 KPOINTS with no shift.

as_dict()[source]

Returns:

MSONable dict.

static automatic(subdivisions)[source]

Convenient static constructor for a fully automatic Kpoint grid, with gamma centered Monkhorst-Pack grids and the number of subdivisions along each reciprocal lattice vector determined by the scheme in the VASP manual.

Parameters:

subdivisions – Parameter determining number of subdivisions along each reciprocal lattice vector.

Returns:

Kpoints object

static automatic_density(structure: Structure, kppa: float, force_gamma: bool = False)[source]

Returns an automatic Kpoint object based on a structure and a kpoint density. Uses Gamma centered meshes for hexagonal cells and Monkhorst-Pack grids otherwise.

Algorithm:

Uses a simple approach scaling the number of divisions along each reciprocal lattice vector proportional to its length.

Parameters:

• structure (Structure) – Input structure

• kppa (float) – Grid density

• force_gamma (bool) – Force a gamma centered mesh (default is to use gamma only for hexagonal cells or odd meshes)

Returns:

Kpoints

static automatic_density_by_lengths(structure: Structure, length_densities: Sequence[float], force_gamma: bool = False)[source]

Returns an automatic Kpoint object based on a structure and a k-point density normalized by lattice constants.

Algorithm:

For a given dimension, the # of k-points is chosen as length_density = # of kpoints * lattice constant, e.g. [50.0, 50.0, 1.0] would have k-points of 50/a x 50/b x 1/c.

Parameters:

• structure (Structure) – Input structure

• length_densities (list[floats]) – Defines the density of k-points in each

• dimension –

• [50.0 (e.g.) –

• 50.0 –

• 1.0]. –

• force_gamma (bool) – Force a gamma centered mesh

Returns:

Kpoints

static automatic_density_by_vol(structure: Structure, kppvol: int, force_gamma: bool = False) → Kpoints[source]

Returns an automatic Kpoint object based on a structure and a kpoint density per inverse Angstrom^3 of reciprocal cell.

Algorithm:

Same as automatic_density()

Parameters:

• structure (Structure) – Input structure

• kppvol (int) – Grid density per Angstrom^(-3) of reciprocal cell

• force_gamma (bool) – Force a gamma centered mesh

Returns:

Kpoints

static automatic_gamma_density(structure: Structure, kppa: float)[source]

Returns an automatic Kpoint object based on a structure and a kpoint density. Uses Gamma centered meshes always. For GW.

Algorithm:

Uses a simple approach scaling the number of divisions along each reciprocal lattice vector proportional to its length.

Parameters:

• structure – Input structure

• kppa – Grid density

static automatic_linemode(divisions, ibz)[source]

Convenient static constructor for a KPOINTS in mode line_mode. gamma centered Monkhorst-Pack grids and the number of subdivisions along each reciprocal lattice vector determined by the scheme in the VASP manual.

Parameters:

• divisions – Parameter determining the number of k-points along each high symmetry line.

• ibz – HighSymmKpath object (pymatgen.symmetry.bandstructure)

Returns:

Kpoints object

classmethod from_dict(d)[source]

Parameters:

d – Dict representation.

Returns:

Kpoints

static from_file(filename)[source]

Reads a Kpoints object from a KPOINTS file.

Parameters:

filename (str) – filename to read from.

Returns:

Kpoints object

static from_str(string)[source]

Reads a Kpoints object from a KPOINTS string.

Parameters:

string (str) – KPOINTS string.

Returns:

Kpoints object

classmethod from_string(*args, **kwds)[source]

from_string is deprecated! Use from_str instead

static gamma_automatic(kpts: tuple[int, int, int] = (1, 1, 1), shift: Vector3D = (0, 0, 0))[source]

Convenient static constructor for an automatic Gamma centered Kpoint grid.

Parameters:

• kpts – Subdivisions N_1, N_2 and N_3 along reciprocal lattice vectors. Defaults to (1,1,1)

• shift – Shift to be applied to the kpoints. Defaults to (0,0,0).

Returns:

Kpoints object

static monkhorst_automatic(kpts: tuple[int, int, int] = (2, 2, 2), shift: Vector3D = (0, 0, 0))[source]

Convenient static constructor for an automatic Monkhorst pack Kpoint grid.

Parameters:

• kpts – Subdivisions N_1, N_2, N_3 along reciprocal lattice vectors. Defaults to (2,2,2)

• shift – Shift to be applied to the kpoints. Defaults to (0,0,0).

Returns:

Kpoints object

property style[source]

Style for kpoint generation. One of Kpoints_supported_modes enum.

Type:

return

supported_modes[source]

alias of KpointsSupportedModes

write_file(filename)[source]

Write Kpoints to a file.

Parameters:

filename (str) – Filename to write to.

class KpointsSupportedModes(value)[source]

Bases: Enum

Enum type of all supported modes for Kpoint generation.

Automatic = 0[source]

Cartesian = 4[source]

Gamma = 1[source]

Line_mode = 3[source]

Monkhorst = 2[source]

Reciprocal = 5[source]

static from_str(s: str) → KpointsSupportedModes[source]

Parameters:

s – String

Returns:

Kpoints_supported_modes

classmethod from_string(*args, **kwds)[source]

from_string is deprecated! Use from_str instead

class Orbital(n, l, j, E, occ)[source]

Bases: tuple

Create new instance of Orbital(n, l, j, E, occ)

E[source]

Alias for field number 3

_asdict()[source]

Return a new dict which maps field names to their values.

_field_defaults = {}[source]

_fields = ('n', 'l', 'j', 'E', 'occ')[source]

classmethod _make(iterable)[source]

Make a new Orbital object from a sequence or iterable

_replace(**kwds)[source]

Return a new Orbital object replacing specified fields with new values

j[source]

Alias for field number 2

l[source]

Alias for field number 1

n[source]

Alias for field number 0

occ[source]

Alias for field number 4

class OrbitalDescription(l, E, Type, Rcut, Type2, Rcut2)[source]

Bases: tuple

Create new instance of OrbitalDescription(l, E, Type, Rcut, Type2, Rcut2)

E[source]

Alias for field number 1

Rcut[source]

Alias for field number 3

Rcut2[source]

Alias for field number 5

Type[source]

Alias for field number 2

Type2[source]

Alias for field number 4

_asdict()[source]

Return a new dict which maps field names to their values.

_field_defaults = {}[source]

_fields = ('l', 'E', 'Type', 'Rcut', 'Type2', 'Rcut2')[source]

classmethod _make(iterable)[source]

Make a new OrbitalDescription object from a sequence or iterable

_replace(**kwds)[source]

Return a new OrbitalDescription object replacing specified fields with new values

l[source]

Alias for field number 0

class Poscar(structure: Structure, comment: str | None = None, selective_dynamics: ArrayLike | None = None, true_names: bool = True, velocities: ArrayLike | None = None, predictor_corrector: ArrayLike | None = None, predictor_corrector_preamble: str | None = None, sort_structure: bool = False)[source]

Bases: MSONable

Object for representing the data in a POSCAR or CONTCAR file. Please note that this current implementation. Most attributes can be set directly.

structure[source]

Associated Structure.

comment[source]

Optional comment string.

true_names[source]

Boolean indication whether Poscar contains actual real names parsed from either a POTCAR or the POSCAR itself.

selective_dynamics[source]

Selective dynamics attribute for each site if available. A Nx3 array of booleans.

velocities[source]

Velocities for each site (typically read in from a CONTCAR). A Nx3 array of floats.

predictor_corrector[source]

Predictor corrector coordinates and derivatives for each site; i.e. a list of three 1x3 arrays for each site (typically read in from a MD CONTCAR).

predictor_corrector_preamble[source]

Predictor corrector preamble contains the predictor-corrector key, POTIM, and thermostat parameters that precede the site-specic predictor corrector data in MD CONTCAR

temperature[source]

Temperature of velocity Maxwell-Boltzmann initialization. Initialized to -1 (MB hasn”t been performed).

Parameters:

• structure (Structure) – Structure object.

• comment (str | None, optional) – Optional comment line for POSCAR. Defaults to unit cell formula of structure. Defaults to None.

• selective_dynamics (ArrayLike | None, optional) – Bool values for selective dynamics, where N is the number of sites. Defaults to None.

• true_names (bool, optional) – Set to False if the names in the POSCAR are not well-defined and ambiguous. This situation arises commonly in VASP < 5 where the POSCAR sometimes does not contain element symbols. Defaults to True.

• velocities (ArrayLike | None, optional) – Velocities for the POSCAR. Typically parsed in MD runs or can be used to initialize velocities. Defaults to None.

• predictor_corrector (ArrayLike | None, optional) – Predictor corrector for the POSCAR. Typically parsed in MD runs. Defaults to None.

• predictor_corrector_preamble (str | None, optional) – Preamble to the predictor corrector. Defaults to None.

• sort_structure (bool, optional) – Whether to sort the structure. Useful if species are not grouped properly together. Defaults to False.

as_dict() → dict[source]

Returns:

MSONable dict.

classmethod from_dict(d: dict) → Poscar[source]

Parameters:

d – Dict representation.

Returns:

Poscar

static from_file(filename, check_for_POTCAR=True, read_velocities=True) → Poscar[source]

Reads a Poscar from a file.

The code will try its best to determine the elements in the POSCAR in the following order:

1. If check_for_POTCAR is True, the code will try to check if a POTCAR is in the same directory as the POSCAR and use elements from that by default. (This is the VASP default sequence of priority). 2. If the input file is VASP5-like and contains element symbols in the 6th line, the code will use that if check_for_POTCAR is False or there is no POTCAR found. 3. Failing (2), the code will check if a symbol is provided at the end of each coordinate.

If all else fails, the code will just assign the first n elements in increasing atomic number, where n is the number of species, to the Poscar. For example, H, He, Li, …. This will ensure at least a unique element is assigned to each site and any analysis that does not require specific elemental properties should work fine.

Parameters:

• filename (str) – File name containing Poscar data.

• check_for_POTCAR (bool) – Whether to check if a POTCAR is present in the same directory as the POSCAR. Defaults to True.

• read_velocities (bool) – Whether to read or not velocities if they are present in the POSCAR. Default is True.

Returns:

Poscar object.

static from_str(data, default_names=None, read_velocities=True)[source]

Reads a Poscar from a string.

The code will try its best to determine the elements in the POSCAR in the following order:

1. If default_names are supplied and valid, it will use those. Usually, default names comes from an external source, such as a POTCAR in the same directory.

2. If there are no valid default names but the input file is VASP5-like and contains element symbols in the 6th line, the code will use that.

3. Failing (2), the code will check if a symbol is provided at the end of each coordinate.

If all else fails, the code will just assign the first n elements in increasing atomic number, where n is the number of species, to the Poscar. For example, H, He, Li, …. This will ensure at least a unique element is assigned to each site and any analysis that does not require specific elemental properties should work fine.

Parameters:

• data (str) – String containing Poscar data.

• default_names ([str]) – Default symbols for the POSCAR file, usually coming from a POTCAR in the same directory.

• read_velocities (bool) – Whether to read or not velocities if they are present in the POSCAR. Default is True.

Returns:

Poscar object.

classmethod from_string(*args, **kwds)[source]

from_string is deprecated! Use from_str instead

get_string(direct: bool = True, vasp4_compatible: bool = False, significant_figures: int = 16) → str[source]

Returns a string to be written as a POSCAR file. By default, site symbols are written, which means compatibility is for vasp >= 5.

Parameters:

• direct (bool) – Whether coordinates are output in direct or Cartesian. Defaults to True.

• vasp4_compatible (bool) – Set to True to omit site symbols on 6th line to maintain backward vasp 4.x compatibility. Defaults to False.

• significant_figures (int) – No. of significant figures to output all quantities. Defaults to 16. Note that positions are output in fixed point, while velocities are output in scientific format.

Returns:

String representation of POSCAR.

property natoms[source]

Sequence of number of sites of each type associated with the Poscar. Similar to 7th line in vasp 5+ POSCAR or the 6th line in vasp 4 POSCAR.

property predictor_corrector[source]

Predictor corrector in Poscar.

property selective_dynamics[source]

Selective dynamics in Poscar.

set_temperature(temperature: float)[source]

Initializes the velocities based on Maxwell-Boltzmann distribution. Removes linear, but not angular drift (same as VASP).

Scales the energies to the exact temperature (microcanonical ensemble) Velocities are given in A/fs. This is the vasp default when direct/cartesian is not specified (even when positions are given in direct coordinates)

Overwrites imported velocities, if any.

Parameters:

temperature (float) – Temperature in Kelvin.

property site_symbols[source]

Sequence of symbols associated with the Poscar. Similar to 6th line in vasp 5+ POSCAR.

property velocities[source]

Velocities in Poscar.

write_file(filename: PathLike, **kwargs)[source]

Writes POSCAR to a file. The supported kwargs are the same as those for the Poscar.get_string method and are passed through directly.

class Potcar(symbols=None, functional=None, sym_potcar_map=None)[source]

Bases: list, MSONable

Object for reading and writing POTCAR files for calculations. Consists of a list of PotcarSingle.

Parameters:

• symbols ([str]) – Element symbols for POTCAR. This should correspond to the symbols used by VASP. E.g., “Mg”, “Fe_pv”, etc.

• functional (str) – Functional used. To know what functional options there are, use Potcar.FUNCTIONAL_CHOICES. Note that VASP has different versions of the same functional. By default, the old PBE functional is used. If you want the newer ones, use PBE_52 or PBE_54. Note that if you intend to compare your results with the Materials Project, you should use the default setting. You can also override the default by setting PMG_DEFAULT_FUNCTIONAL in your .pmgrc.yaml.

• sym_potcar_map (dict) – Allows a user to specify a specific element symbol to raw POTCAR mapping.

FUNCTIONAL_CHOICES = ('PBE', 'PBE_52', 'PBE_54', 'LDA', 'LDA_52', 'LDA_54', 'PW91', 'LDA_US', 'PW91_US', 'Perdew_Zunger81')[source]

as_dict()[source]

Returns:

MSONable dict representation

classmethod from_dict(d)[source]

Parameters:

d – Dict representation

Returns:

Potcar

static from_file(filename: str)[source]

Reads Potcar from file.

Parameters:

filename – Filename

Returns:

Potcar

set_symbols(symbols, functional=None, sym_potcar_map=None)[source]

Initialize the POTCAR from a set of symbols. Currently, the POTCARs can be fetched from a location specified in .pmgrc.yaml. Use pmg config to add this setting.

Parameters:

• symbols ([str]) – A list of element symbols

• functional (str) – The functional to use. If None, the setting PMG_DEFAULT_FUNCTIONAL in .pmgrc.yaml is used, or if this is not set, it will default to PBE.

• sym_potcar_map (dict) – A map of symbol:raw POTCAR string. If sym_potcar_map is specified, POTCARs will be generated from the given map data rather than the config file location.

property spec[source]

Get the atomic symbols and hash of all the atoms in the POTCAR file.

property symbols[source]

Get the atomic symbols of all the atoms in the POTCAR file.

write_file(filename: str) → None[source]

Write Potcar to a file.

Parameters:

filename (str) – filename to write to.

class PotcarSingle(data, symbol=None)[source]

Bases: object

Object for a single POTCAR. The builder assumes the POTCAR contains the complete untouched data in “data” as a string and a dict of keywords.

data[source]

POTCAR data as a string.

keywords[source]

Keywords parsed from the POTCAR as a dict. All keywords are also accessible as attributes in themselves. E.g., potcar.enmax, potcar.encut, etc.

md5 hashes of the entire POTCAR file and the actual data are validated against a database of known good hashes. Appropriate warnings or errors are raised if a POTCAR hash fails validation.

Parameters:

• data – Complete and single potcar file as a string.

• symbol – POTCAR symbol corresponding to the filename suffix e.g. “Tm_3” for POTCAR.TM_3”. If not given, pymatgen will attempt to extract the symbol from the file itself. However, this is not always reliable!

property atomic_no: int[source]

Attempt to return the atomic number based on the VRHFIN keyword.

property electron_configuration[source]

Electronic configuration of the PotcarSingle.

Type:

return

property element[source]

Attempt to return the atomic symbol based on the VRHFIN keyword.

static from_file(filename: str) → PotcarSingle[source]

Reads PotcarSingle from file.

Parameters:

filename – Filename.

Returns:

PotcarSingle.

static from_symbol_and_functional(symbol: str, functional: str | None = None)[source]

Makes a PotcarSingle from a symbol and functional.

Parameters:

• symbol – Symbol, e.g., Li_sv

• functional – E.g., PBE

Returns:

PotcarSingle

property functional[source]

Functional associated with PotcarSingle.

Type:

return

property functional_class[source]

Functional class associated with PotcarSingle.

Type:

return

functional_dir = {'LDA': 'POT_LDA_PAW', 'LDA_52': 'POT_LDA_PAW_52', 'LDA_54': 'POT_LDA_PAW_54', 'LDA_US': 'POT_LDA_US', 'PBE': 'POT_GGA_PAW_PBE', 'PBE_52': 'POT_GGA_PAW_PBE_52', 'PBE_54': 'POT_GGA_PAW_PBE_54', 'PW91': 'POT_GGA_PAW_PW91', 'PW91_US': 'POT_GGA_US_PW91', 'Perdew_Zunger81': 'POT_LDA_PAW'}[source]

functional_tags = {'91': {'class': 'GGA', 'name': 'PW91'}, 'am': {'class': 'GGA', 'name': 'AM05'}, 'ca': {'class': 'LDA', 'name': 'Perdew-Zunger81'}, 'hl': {'class': 'LDA', 'name': 'Hedin-Lundquist'}, 'lm': {'class': 'GGA', 'name': 'Langreth-Mehl-Hu'}, 'pb': {'class': 'GGA', 'name': 'Perdew-Becke'}, 'pe': {'class': 'GGA', 'name': 'PBE'}, 'ps': {'class': 'GGA', 'name': 'PBEsol'}, 'pw': {'class': 'GGA', 'name': 'PW86'}, 'rp': {'class': 'GGA', 'name': 'revPBE'}, 'wi': {'class': 'LDA', 'name': 'Wigner Interpolation'}}[source]

get_potcar_file_hash()[source]

Computes a md5 hash of the entire PotcarSingle.

This hash corresponds to the md5 hash of the POTCAR file itself.

Returns:

Hash value.

get_potcar_hash()[source]

Computes a md5 hash of the metadata defining the PotcarSingle.

Returns:

Hash value.

get_sha256_file_hash()[source]

Computes a SHA256 hash of the PotcarSingle EXCLUDING lines starting with ‘SHA256’ and ‘CPRY’.

This hash corresponds to the sha256 hash printed in the header of modern POTCAR files.

Returns:

Hash value.

identify_potcar(mode: Literal['data', 'file'] = 'data')[source]

Identify the symbol and compatible functionals associated with this PotcarSingle.

This method checks the md5 hash of either the POTCAR metadadata (PotcarSingle.hash) or the entire POTCAR file (PotcarSingle.file_hash) against a database of hashes for POTCARs distributed with VASP 5.4.4.

Parameters:

mode ('data' | 'file') – ‘data’ mode checks the hash of the POTCAR metadata in self.PSCTR, while ‘file’ mode checks the hash of the entire POTCAR file.

Returns:

List of symbols associated with the PotcarSingle potcar_functionals (List): List of potcar functionals associated with

the PotcarSingle

Return type:

symbol (List)

property nelectrons[source]

Number of electrons

Type:

return

parse_functions = {'COPYR': <function _parse_string>, 'DEXC': <function _parse_float>, 'EATOM': <function _parse_float>, 'EAUG': <function _parse_float>, 'EMMIN': <function _parse_float>, 'ENMAX': <function _parse_float>, 'ENMIN': <function _parse_float>, 'GGA': <function _parse_list>, 'ICORE': <function _parse_int>, 'IUNSCR': <function _parse_int>, 'LCOR': <function _parse_bool>, 'LEXCH': <function _parse_string>, 'LPAW': <function _parse_bool>, 'LULTRA': <function _parse_bool>, 'LUNSCR': <function _parse_bool>, 'NDATA': <function _parse_int>, 'POMASS': <function _parse_float>, 'QCUT': <function _parse_float>, 'QGAM': <function _parse_float>, 'RAUG': <function _parse_float>, 'RCLOC': <function _parse_float>, 'RCORE': <function _parse_float>, 'RDEP': <function _parse_float>, 'RDEPT': <function _parse_float>, 'RMAX': <function _parse_float>, 'RPACOR': <function _parse_float>, 'RRKJ': <function _parse_list>, 'RWIGS': <function _parse_float>, 'SHA256': <function _parse_string>, 'STEP': <function _parse_list>, 'TITEL': <function _parse_string>, 'VRHFIN': <function _parse_string>, 'ZVAL': <function _parse_float>}[source]

property potential_type: str[source]

Type of PSP. E.g., US, PAW, etc.

Type:

return

property symbol[source]

The POTCAR symbol, e.g. W_pv

Type:

return

verify_potcar() → tuple[bool, bool][source]

Attempts to verify the integrity of the POTCAR data.

This method checks the whole file (removing only the SHA256 metadata) against the SHA256 hash in the header if this is found. If no SHA256 hash is found in the file, the file hash (md5 hash of the whole file) is checked against all POTCAR file hashes known to pymatgen.

Returns:

(bool, bool)

has_sh256 and passed_hash_check are returned.

write_file(filename: str) → None[source]

Writes PotcarSingle to a file. :param filename: Filename.

exception UnknownPotcarWarning[source]

Bases: UserWarning

Warning raised when POTCAR hashes do not pass validation.

class VaspInput(incar, kpoints, poscar, potcar, optional_files=None, **kwargs)[source]

Bases: dict, MSONable

Class to contain a set of vasp input objects corresponding to a run.

Initializes a VaspInput object with the given input files.

Parameters:

• incar (Incar) – The Incar object.

• kpoints (Kpoints) – The Kpoints object.

• poscar (Poscar) – The Poscar object.

• potcar (Potcar) – The Potcar object.

• optional_files (dict) – Other input files supplied as a dict of {filename: object}. The object should follow standard pymatgen conventions in implementing a as_dict() and from_dict method.

• **kwargs – Additional keyword arguments to be stored in the VaspInput object.

as_dict()[source]

Returns:

MSONable dict.

classmethod from_dict(d)[source]

Parameters:

d – Dict representation.

Returns:

VaspInput

static from_directory(input_dir, optional_files=None)[source]

Read in a set of VASP input from a directory. Note that only the standard INCAR, POSCAR, POTCAR and KPOINTS files are read unless optional_filenames is specified.

Parameters:

• input_dir (str) – Directory to read VASP input from.

• optional_files (dict) – Optional files to read in as well as a dict of {filename: Object type}. Object type must have a static method from_file.

run_vasp(run_dir: PathLike = '.', vasp_cmd: list | None = None, output_file: PathLike = 'vasp.out', err_file: PathLike = 'vasp.err')[source]

Write input files and run VASP.

Parameters:

• run_dir – Where to write input files and do the run.

• vasp_cmd – Args to be supplied to run VASP. Otherwise, the PMG_VASP_EXE in .pmgrc.yaml is used.

• output_file – File to write output.

• err_file – File to write err.

write_input(output_dir='.', make_dir_if_not_present=True)[source]

Write VASP input to a directory.

Parameters:

• output_dir (str) – Directory to write to. Defaults to current directory (“.”).

• make_dir_if_not_present (bool) – Create the directory if not present. Defaults to True.

_parse_bool(s)[source]

_parse_float(s)[source]

_parse_int(s)[source]

_parse_list(s)[source]

_parse_string(s)[source]

pymatgen.io.vasp.optics module

Classes for parsing and manipulating VASP optical properties calculations.

class DielectricFunctionCalculator(cder_real: NDArray, cder_imag: NDArray, eigs: NDArray, kweights: NDArray, nedos: int, deltae: float, ismear: int, sigma: float, efermi: float, cshift: float, ispin: int, volume: float)[source]

Bases: MSONable

Class for postprocessing VASP optical properties calculations.

This objects helps load the different parameters from the vasprun.xml file but allows users to override them as needed.

The standard vasprun.xml from an LOPTICS=.True. calculation already contains the complex frequency dependent dielectric functions. However you have no way to decompose the different contributions. Since the WAVEDER file is also written during an optical calculation, you can reconstruct the dielectric functions purely in Python and have full control over contribution from different bands and k-points.

VASP’s linear optics follow these steps:

• Calculate the imaginary part

• Perform symmetry operations (this is not implemented here)

• Calculate the real part

Currently, this Calculator only works for ISYM=0 calculations since we cannot guarantee that our externally defined symmetry operations are the same as VASP’s. This can be fixed by printing the symmetry operators into the vasprun.xml file. If this happens in future versions of VASP, we can dramatically speed up the calculations here by considering only the irreducible kpoints.

property cder[source]

Complex CDER from WAVEDER.

cder_imag: NDArray[source]

cder_real: NDArray[source]

cshift: float[source]

deltae: float[source]

efermi: float[source]

eigs: NDArray[source]

classmethod from_directory(directory: Path | str)[source]

Construct a DielectricFunction from a directory containing vasprun.xml and WAVEDER files.

classmethod from_vasp_objects(vrun: Vasprun, waveder: Waveder)[source]

Construct a DielectricFunction from Vasprun, Kpoint, and Waveder objects.

Parameters:

• vrun – Vasprun object

• kpoint – Kpoint object

• waveder – Waveder object

get_epsilon(idir: int, jdir: int, efermi: float | None = None, nedos: int | None = None, deltae: float | None = None, ismear: int | None = None, sigma: float | None = None, cshift: float | None = None, mask: NDArray | None = None) → tuple[NDArray, NDArray][source]

Compute the frequency dependent dielectric function.

Parameters:

• idir – First direction of the dielectric tensor

• jdir – Second direction of the dielectric tensor

• efermi – Fermi energy

• nedos – Number of points in the DOS

• deltae – Energy step in the DOS

• ismear – Smearing method (only has 0:gaussian, >0:Methfessel-Paxton)

• sigma – Smearing width

• cshift – Complex shift used for Kramer-Kronig transformation

• mask – Mask for the bands/kpoint/spin index to include in the calculation

ismear: int[source]

ispin: int[source]

kweights: NDArray[source]

nedos: int[source]

plot_weighted_transition_data(idir: int, jdir: int, mask: NDArray | None = None, min_val: float = 0.0)[source]

Data for plotting the weight matrix elements as a scatter plot.

Since the computation of the final spectrum (especially the smearing part) is still fairly expensive. This function can be used to check the values of some portion of the spectrum (defined by the mask). In a sense, we are lookin at the imaginary part of the dielectric function before the smearing is applied.

Parameters:

• idir – First direction of the dielectric tensor.

• jdir – Second direction of the dielectric tensor.

• mask – Mask to apply to the CDER for the bands/kpoint/spin index to include in the calculation

• min_val – Minimum value below this value the matrix element will not be shown.

sigma: float[source]

volume: float[source]

delta_func(x, ismear)[source]

Replication of VASP’s delta function.

delta_methfessel_paxton(x, n)[source]

D_n (x) = exp -x^2 * sum_i=0^n A_i H_2i(x) where H is a Hermite polynomial and A_i = (-1)^i / ( i! 4^i sqrt(pi) ).

epsilon_imag(cder: NDArray, eigs: NDArray, kweights: ArrayLike, efermi: float, nedos: int, deltae: float, ismear: int, sigma: float, idir: int, jdir: int, mask: NDArray | None = None)[source]

Replicate the EPSILON_IMAG function of VASP.

Parameters:

• cder – The data written to the WAVEDER (nbands, nbands, nkpoints, nspin, diri, dirj)

• eigs – The eigenvalues (nbands, nkpoints, nspin)

• kweights – The kpoint weights (nkpoints)

• efermi – The fermi energy

• nedos – The sampling of the energy values

• deltae – The energy grid spacing

• ismear – The smearing parameter used by the step_func.

• sigma – The width of the smearing

• idir – The first direction of the dielectric tensor

• jdir – The second direction of the dielectric tensor

• mask – Mask for the bands/kpoint/spin index to include in the calculation

Returns:

Array of size nedos with the imaginary part of the dielectric function.

Return type:

np.array

get_delta(x0: float, sigma: float, nx: int, dx: float, ismear: int = 3)[source]

Get the smeared delta function to be added to form the spectrum.

This replaces the SLOT function from VASP. Uses finite differences instead of evaluating the delta function since the step function is more likely to have analytic form.

Parameters:

• x0 – The center of the dielectric function.

• sigma – The width of the smearing

• nx – The number of grid points in the output grid.

• dx – The gridspacing of the output grid.

• ismear – The smearing parameter used by the step_func.

Returns:

Array of size nx with delta function on the desired outputgrid.

Return type:

np.array

get_step(x0, sigma, nx, dx, ismear)[source]

Get the smeared step function to be added to form the spectrum.

This replaces the SLOT function from VASP.

Parameters:

• x0 – The center of the dielectric function.

• sigma – The width of the smearing

• nx – The number of grid points in the output grid.

• dx – The gridspacing of the output grid.

• ismear – The smearing parameter used by the step_func.

Returns:

Array of size nx with step function on the desired outputgrid.

Return type:

np.array

kramers_kronig(eps: np.ndarray, nedos: int, deltae: float, cshift: float = 0.1) → NDArray[source]

Perform the Kramers-Kronig transformation.

Perform the Kramers-Kronig transformation exactly as VASP does it. The input eps should be complex and the imaginary part of the dielectric function should be stored as the real part of the complex input array. The output should be the complex dielectric function.

Parameters:

• eps – The dielectric function with the imaginary part stored as the real part and nothing in the imaginary part.

• nedos – The sampling of the energy values

• deltae – The energy grid spacing

• cshift – The shift of the imaginary part of the dielectric function.

Returns:

Array of size nedos with the complex dielectric function.

Return type:

np.array

step_func(x, ismear)[source]

Replication of VASP’s step function.

step_methfessel_paxton(x, n)[source]

S_n (x) = (1 + erf x)/2 - exp -x^2 * sum_i=1^n A_i H_{2i-1}(x) where H is a Hermite polynomial and A_i = (-1)^i / ( i! 4^i sqrt(pi) ).

pymatgen.io.vasp.outputs module

Classes for reading/manipulating/writing VASP output files.

class BSVasprun(filename: str, parse_projected_eigen: bool | str = False, parse_potcar_file: bool | str = False, occu_tol: float = 1e-08, separate_spins: bool = False)[source]

Bases: Vasprun

A highly optimized version of Vasprun that parses only eigenvalues for bandstructures. All other properties like structures, parameters, etc. are ignored.

Parameters:

• filename – Filename to parse

• parse_projected_eigen – Whether to parse the projected eigenvalues. Defaults to False. Set to True to obtain projected eigenvalues. Note that this can take an extreme amount of time and memory. So use this wisely.

• parse_potcar_file –

  Whether to parse the potcar file to read the potcar hashes for the potcar_spec attribute. Defaults to True, where no hashes will be determined and the potcar_spec dictionaries will read {“symbol”: ElSymbol, “hash”: None}. By Default, looks in the same directory as the vasprun.xml, with same extensions as

  Vasprun.xml. If a string is provided, looks at that filepath.

• occu_tol – Sets the minimum tol for the determination of the vbm and cbm. Usually the default of 1e-8 works well enough, but there may be pathological cases.

• separate_spins (bool) – Whether the band gap, CBM, and VBM should be reported for each individual spin channel. Defaults to False, which computes the eigenvalue band properties independent of the spin orientation. If True, the calculation must be spin-polarized.

as_dict()[source]

JSON-serializable dict representation.

class Chgcar(poscar, data, data_aug=None)[source]

Bases: VolumetricData

Simple object for reading a CHGCAR file.

Parameters:

• poscar (Poscar or Structure) – Object containing structure.

• data – Actual data.

• data_aug – Augmentation charge data.

static from_file(filename: str)[source]

Read a CHGCAR file.

Parameters:

filename – Filename

Returns:

Chgcar

property net_magnetization[source]

Net magnetization from Chgcar

Type:

return

class Dynmat(filename)[source]

Bases: object

Object for reading a DYNMAT file.

data[source]

A nested dict containing the DYNMAT data of the form:: [atom <int>][disp <int>][‘dispvec’] =

displacement vector (part of first line in dynmat block, e.g. “0.01 0 0”)

[atom <int>][disp <int>][‘dynmat’] =

<list> list of dynmat lines for this atom and this displacement

Authors: Patrick Huck

Parameters:

filename – Name of file containing DYNMAT.

get_phonon_frequencies()[source]

Calculate phonon frequencies.

property masses[source]

Returns the list of atomic masses.

property natoms[source]

Returns the number of atoms.

property ndisps[source]

Returns the number of displacements.

property nspecs[source]

Returns the number of species.

class Eigenval(filename, occu_tol=1e-08, separate_spins=False)[source]

Bases: object

Object for reading EIGENVAL file.

filename[source]

string containing input filename

occu_tol[source]

tolerance for determining occupation in band properties

ispin[source]

spin polarization tag (int)

nelect[source]

number of electrons

nkpt[source]

number of kpoints

nbands[source]

number of bands

kpoints[source]

list of kpoints

kpoints_weights[source]

weights of each kpoint in the BZ, should sum to 1.

eigenvalues[source]

Eigenvalues as a dict of {(spin): np.ndarray(shape=(nkpt, nbands, 2))}. This representation is based on actual ordering in VASP and is meant as an intermediate representation to be converted into proper objects. The kpoint index is 0-based (unlike the 1-based indexing in VASP).

Reads input from filename to construct Eigenval object.

Parameters:

• filename (str) – filename of EIGENVAL to read in

• occu_tol (float) – tolerance for determining band gap

• separate_spins (bool) – whether the band gap, CBM, and VBM should be reported for each individual spin channel. Defaults to False, which computes the eigenvalue band properties independent of the spin orientation. If True, the calculation must be spin-polarized.

Returns:

a pymatgen.io.vasp.outputs.Eigenval object

property eigenvalue_band_properties[source]

Band properties from the eigenvalues as a tuple, (band gap, cbm, vbm, is_band_gap_direct). In the case of separate_spins=True, the band gap, cbm, vbm, and is_band_gap_direct are each lists of length 2, with index 0 representing the spin-up channel and index 1 representing the spin-down channel.

class Elfcar(poscar, data)[source]

Bases: VolumetricData

Read an ELFCAR file which contains the Electron Localization Function (ELF) as calculated by VASP.

For ELF, “total” key refers to Spin.up, and “diff” refers to Spin.down.

This also contains information on the kinetic energy density.

Parameters:

• poscar (Poscar or Structure) – Object containing structure.

• data – Actual data.

classmethod from_file(filename)[source]

Reads a ELFCAR file.

Parameters:

filename – Filename

Returns:

Elfcar

get_alpha()[source]

Get the parameter alpha where ELF = 1/(1+alpha^2).

class Locpot(poscar, data)[source]

Bases: VolumetricData

Simple object for reading a LOCPOT file.

Parameters:

• poscar (Poscar) – Poscar object containing structure.

• data – Actual data.

classmethod from_file(filename, **kwargs)[source]

Reads a LOCPOT file.

Parameters:

filename – Filename

Returns:

Locpot

class Oszicar(filename)[source]

Bases: object

A basic parser for an OSZICAR output from VASP. In general, while the OSZICAR is useful for a quick look at the output from a VASP run, we recommend that you use the Vasprun parser instead, which gives far richer information about a run.

electronic_steps[source]

All electronic steps as a list of list of dict. e.g., [[{“rms”: 160.0, “E”: 4507.24605593, “dE”: 4507.2, “N”: 1, “deps”: -17777.0, “ncg”: 16576}, …], [….] where electronic_steps[index] refers the list of electronic steps in one ionic_step, electronic_steps[index][subindex] refers to a particular electronic step at subindex in ionic step at index. The dict of properties depends on the type of VASP run, but in general, “E”, “dE” and “rms” should be present in almost all runs.

ionic_steps:

All ionic_steps as a list of dict, e.g., [{“dE”: -526.36, “E0”: -526.36024, “mag”: 0.0, “F”: -526.36024}, …] This is the typical output from VASP at the end of each ionic step.

Parameters:

filename (str) – Filename of file to parse.

property all_energies[source]

Compilation of all energies from all electronic steps and ionic steps as a tuple of list of energies, e.g., ((4507.24605593, 143.824705755, -512.073149912, …), …).

as_dict()[source]

Returns:

MSONable dict

property final_energy[source]

class Outcar(filename)[source]

Bases: object

Parser for data in OUTCAR that is not available in Vasprun.xml.

Note, this class works a bit differently than most of the other VaspObjects, since the OUTCAR can be very different depending on which “type of run” performed.

Creating the OUTCAR class with a filename reads “regular parameters” that are always present.

magnetization[source]

Magnetization on each ion as a tuple of dict, e.g., ({“d”: 0.0, “p”: 0.003, “s”: 0.002, “tot”: 0.005}, … ) Note that this data is not always present. LORBIT must be set to some other value than the default.

chemical_shielding[source]

chemical shielding on each ion as a dictionary with core and valence contributions

unsym_cs_tensor[source]

Unsymmetrized chemical shielding tensor matrixes on each ion as a list. e.g., [[[sigma11, sigma12, sigma13],

[sigma21, sigma22, sigma23], [sigma31, sigma32, sigma33]], …

[[sigma11, sigma12, sigma13],

[sigma21, sigma22, sigma23], [sigma31, sigma32, sigma33]]]

cs_g0_contribution[source]

G=0 contribution to chemical shielding. 2D rank 3 matrix

cs_core_contribution[source]

Core contribution to chemical shielding. dict. e.g., {‘Mg’: -412.8, ‘C’: -200.5, ‘O’: -271.1}

efg[source]

Electric Field Gradient (EFG) tensor on each ion as a tuple of dict, e.g., ({“cq”: 0.1, “eta”, 0.2, “nuclear_quadrupole_moment”: 0.3},

{“cq”: 0.7, “eta”, 0.8, “nuclear_quadrupole_moment”: 0.9}, …)

charge[source]

Charge on each ion as a tuple of dict, e.g., ({“p”: 0.154, “s”: 0.078, “d”: 0.0, “tot”: 0.232}, …) Note that this data is not always present. LORBIT must be set to some other value than the default.

is_stopped[source]

True if OUTCAR is from a stopped run (using STOPCAR, see VASP Manual).

run_stats[source]

Various useful run stats as a dict including “System time (sec)”, “Total CPU time used (sec)”, “Elapsed time (sec)”, “Maximum memory used (kb)”, “Average memory used (kb)”, “User time (sec)”, “cores”

elastic_tensor[source]

Total elastic moduli (Kbar) is given in a 6x6 array matrix.

drift[source]

Total drift for each step in eV/Atom

ngf[source]

Dimensions for the Augementation grid

..attribute: final_energy_contribs

Individual contributions to the total final energy as a dictionary. Include contirbutions from keys, e.g.: {‘DENC’: -505778.5184347, ‘EATOM’: 15561.06492564, ‘EBANDS’: -804.53201231, ‘EENTRO’: -0.08932659, ‘EXHF’: 0.0, ‘Ediel_sol’: 0.0, ‘PAW double counting’: 664.6726974100002, ‘PSCENC’: 742.48691646, ‘TEWEN’: 489742.86847338, ‘XCENC’: -169.64189814}

efermi[source]

Fermi energy

filename[source]

Filename

final_energy[source]

Final energy after extrapolation of sigma back to 0, i.e. energy(sigma->0).

final_energy_wo_entrp[source]

Final energy before extrapolation of sigma, i.e. energy without entropy.

final_fr_energy[source]

Final “free energy”, i.e. free energy TOTEN

has_onsite_density_matrices[source]

Boolean for if onsite density matrices have been set

lcalcpol[source]

If LCALCPOL has been set

lepsilon[source]

If LEPSILON has been set

nelect[source]

Returns the number of electrons in the calculation

spin[source]

If spin-polarization was enabled via ISPIN

total_mag[source]

Total magnetization (in terms of the number of unpaired electrons)

One can then call a specific reader depending on the type of run being performed. These are currently: read_igpar(), read_lepsilon() and read_lcalcpol(), read_core_state_eign(), read_avg_core_pot().

See the documentation of those methods for more documentation.

Authors: Rickard Armiento, Shyue Ping Ong

Parameters:

filename (str) – OUTCAR filename to parse.

static _parse_sci_notation(line)[source]

Method to parse lines with values in scientific notation and potentially without spaces in between the values. This assumes that the scientific notation always lists two digits for the exponent, e.g. 3.535E-02 :param line: line to parse.

Returns: an array of numbers if found, or empty array if not

as_dict()[source]

Returns:

MSONable dict.

read_avg_core_poten()[source]

Read the core potential at each ionic step.

Returns:

A list for each ionic step containing a list of the average core potentials for each atom: [[avg core pot]].

Example

The average core potential of the 2nd atom of the structure at the last ionic step is: [-1][1]

read_chemical_shielding()[source]

Parse the NMR chemical shieldings data. Only the second part “absolute, valence and core” will be parsed. And only the three right most field (ISO_SHIELDING, SPAN, SKEW) will be retrieved.

Returns:

List of chemical shieldings in the order of atoms from the OUTCAR. Maryland notation is adopted.

read_core_state_eigen()[source]

Read the core state eigenenergies at each ionic step.

Returns:

[core state eig]}]. The core state eigenenergie list for each AO is over all ionic step.

Return type:

A list of dict over the atom such as [{“AO”

Example

The core state eigenenergie of the 2s AO of the 6th atom of the structure at the last ionic step is [5][“2s”][-1]

read_corrections(reverse=True, terminate_on_match=True)[source]

Reads the dipol qudropol corrections into the Outcar.data[“dipol_quadrupol_correction”].

Parameters:

• reverse – Whether to start from end of OUTCAR.

• terminate_on_match – Whether to terminate once match is found.

read_cs_core_contribution()[source]

Parse the core contribution of NMR chemical shielding.

Returns: G0 contribution matrix as list of list.

read_cs_g0_contribution()[source]

Parse the G0 contribution of NMR chemical shielding.

Returns:

G0 contribution matrix as list of list.

read_cs_raw_symmetrized_tensors()[source]

Parse the matrix form of NMR tensor before corrected to table.

Returns:

nsymmetrized tensors list in the order of atoms.

read_elastic_tensor()[source]

Parse the elastic tensor data.

Returns:

6x6 array corresponding to the elastic tensor from the OUTCAR.

read_electrostatic_potential()[source]

Parses the eletrostatic potential for the last ionic step.

read_fermi_contact_shift()[source]

Output example: Fermi contact (isotropic) hyperfine coupling parameter (MHz) ————————————————————- ion A_pw A_1PS A_1AE A_1c A_tot ————————————————————-

1 -0.002 -0.002 -0.051 0.000 -0.052 2 -0.002 -0.002 -0.051 0.000 -0.052 3 0.056 0.056 0.321 -0.048 0.321

[-0.002, -0.002, -0.051, 0.0, -0.052], [0.056, 0.056, 0.321, -0.048, 0.321]] from ‘fch’ data.

read_freq_dielectric()[source]

Parses the frequency dependent dielectric function (obtained with LOPTICS). Frequencies (in eV) are in self.frequencies, and dielectric tensor function is given as self.dielectric_tensor_function.

read_igpar()[source]

Renders accessible:

er_ev = e<r>_ev (dictionary with Spin.up/Spin.down as keys) er_bp = e<r>_bp (dictionary with Spin.up/Spin.down as keys) er_ev_tot = spin up + spin down summed er_bp_tot = spin up + spin down summed p_elc = spin up + spin down summed p_ion = spin up + spin down summed.

(See VASP section “LBERRY, IGPAR, NPPSTR, DIPOL tags” for info on what these are).

read_internal_strain_tensor()[source]

Reads the internal strain tensor and populates self.internal_strain_tensor with an array of voigt notation

tensors for each site.

read_lcalcpol()[source]

Reads the lcalpol.

# TODO: Document the actual variables.

read_lepsilon()[source]

Reads an LEPSILON run.

# TODO: Document the actual variables.

read_lepsilon_ionic()[source]

Reads an LEPSILON run, the ionic component.

# TODO: Document the actual variables.

read_neb(reverse=True, terminate_on_match=True)[source]

Reads NEB data. This only works with OUTCARs from both normal VASP NEB calculations or from the CI NEB method implemented by Henkelman et al.

Parameters:

• reverse (bool) – Read files in reverse. Defaults to false. Useful for large files, esp OUTCARs, especially when used with terminate_on_match. Defaults to True here since we usually want only the final value.

• terminate_on_match (bool) – Whether to terminate when there is at least one match in each key in pattern. Defaults to True here since we usually want only the final value.

Renders accessible:

tangent_force - Final tangent force. energy - Final energy. These can be accessed under Outcar.data[key]

read_nmr_efg()[source]

Parse the NMR Electric Field Gradient interpreted values.

Returns:

Electric Field Gradient tensors as a list of dict in the order of atoms from OUTCAR. Each dict key/value pair corresponds to a component of the tensors.

read_nmr_efg_tensor()[source]

Parses the NMR Electric Field Gradient Raw Tensors.

Returns:

A list of Electric Field Gradient Tensors in the order of Atoms from OUTCAR

read_onsite_density_matrices()[source]

Parse the onsite density matrices, returns list with index corresponding to atom index in Structure.

read_pattern(patterns, reverse=False, terminate_on_match=False, postprocess=<class 'str'>)[source]

General pattern reading. Uses monty’s regrep method. Takes the same arguments.

Parameters:

• patterns (dict) – A dict of patterns, e.g., {“energy”: r”energy\(sigma->0\)\s+=\s+([\d\-.]+)”}.

• reverse (bool) – Read files in reverse. Defaults to false. Useful for large files, esp OUTCARs, especially when used with terminate_on_match.

• terminate_on_match (bool) – Whether to terminate when there is at least one match in each key in pattern.

• postprocess (callable) – A post processing function to convert all matches. Defaults to str, i.e., no change.

Renders accessible:

Any attribute in patterns. For example, {“energy”: r”energy\(sigma->0\)\s+=\s+([\d\-.]+)”} will set the value of self.data[“energy”] = [[-1234], [-3453], …], to the results from regex and postprocess. Note that the returned values are lists of lists, because you can grep multiple items on one line.

read_piezo_tensor()[source]

Parse the piezo tensor data.

read_pseudo_zval()[source]

Create pseudopotential ZVAL dictionary.

read_table_pattern(header_pattern, row_pattern, footer_pattern, postprocess=<class 'str'>, attribute_name=None, last_one_only=True, first_one_only=False)[source]

Parse table-like data. A table composes of three parts: header, main body, footer. All the data matches “row pattern” in the main body will be returned.

Parameters:

• header_pattern (str) – The regular expression pattern matches the table header. This pattern should match all the text immediately before the main body of the table. For multiple sections table match the text until the section of interest. MULTILINE and DOTALL options are enforced, as a result, the “.” meta-character will also match “n” in this section.

• row_pattern (str) – The regular expression matches a single line in the table. Capture interested field using regular expression groups.

• footer_pattern (str) – The regular expression matches the end of the table. E.g. a long dash line.

• postprocess (callable) – A post processing function to convert all matches. Defaults to str, i.e., no change.

• attribute_name (str) – Name of this table. If present the parsed data will be attached to “data. e.g. self.data[“efg”] = […]

• last_one_only (bool) – All the tables will be parsed, if this option is set to True, only the last table will be returned. The enclosing list will be removed. i.e. Only a single table will be returned. Default to be True. Incompatible with first_one_only.

• first_one_only (bool) – Only the first occurrence of the table will be parsed and the parsing procedure will stop. The enclosing list will be removed. i.e. Only a single table will be returned. Incompatible with last_one_only.

Returns:

List of tables. 1) A table is a list of rows. 2) A row if either a list of attribute values in case the capturing group is defined without name in row_pattern, or a dict in case that named capturing groups are defined by row_pattern.

class Procar(filename)[source]

Bases: object

Object for reading a PROCAR file.

data[source]

The PROCAR data of the form below. It should VASP uses 1-based indexing, but all indices are converted to 0-based here.:

{
    spin: nd.array accessed with (k-point index, band index,
                                  ion index, orbital index)
}

weights[source]

The weights associated with each k-point as an nd.array of length nkpoints.

..attribute:: phase_factors

Phase factors, where present (e.g. LORBIT = 12). A dict of the form: {

spin: complex nd.array accessed with (k-point index, band index,

ion index, orbital index)

}

..attribute:: nbands

Number of bands

..attribute:: nkpoints

Number of k-points

..attribute:: nions

Number of ions

Parameters:

filename – Name of file containing PROCAR.

get_occupation(atom_index, orbital)[source]

Returns the occupation for a particular orbital of a particular atom.

Parameters:

• atom_num (int) – Index of atom in the PROCAR. It should be noted that VASP uses 1-based indexing for atoms, but this is converted to 0-based indexing in this parser to be consistent with representation of structures in pymatgen.

• orbital (str) – An orbital. If it is a single character, e.g., s, p, d or f, the sum of all s-type, p-type, d-type or f-type orbitals occupations are returned respectively. If it is a specific orbital, e.g., px, dxy, etc., only the occupation of that orbital is returned.

Returns:

Sum occupation of orbital of atom.

get_projection_on_elements(structure: Structure)[source]

Method returning a dictionary of projections on elements.

Parameters:

structure (Structure) – Input structure.

Returns:

[k index][b index][{Element:values}]]

Return type:

a dictionary in the {Spin.up

exception UnconvergedVASPWarning[source]

Bases: Warning

Warning for unconverged vasp run.

exception VaspParseError[source]

Bases: ParseError

Exception class for VASP parsing.

class Vasprun(filename, ionic_step_skip=None, ionic_step_offset=0, parse_dos=True, parse_eigen=True, parse_projected_eigen=False, parse_potcar_file=True, occu_tol=1e-08, separate_spins=False, exception_on_bad_xml=True)[source]

Bases: MSONable

Vastly improved cElementTree-based parser for vasprun.xml files. Uses iterparse to support incremental parsing of large files. Speedup over Dom is at least 2x for smallish files (~1Mb) to orders of magnitude for larger files (~10Mb).

VASP results

ionic_steps[source]

All ionic steps in the run as a list of {“structure”: structure at end of run, “electronic_steps”: {All electronic step data in vasprun file}, “stresses”: stress matrix}

tdos[source]

Total dos calculated at the end of run.

idos[source]

Integrated dos calculated at the end of run.

pdos[source]

List of list of PDos objects. Access as pdos[atomindex][orbitalindex]

efermi[source]

Fermi energy

eigenvalues[source]

Available only if parse_eigen=True. Final eigenvalues as a dict of {(spin, kpoint index):[[eigenvalue, occu]]}. This representation is based on actual ordering in VASP and is meant as an intermediate representation to be converted into proper objects. The kpoint index is 0-based (unlike the 1-based indexing in VASP).

projected_eigenvalues[source]

Final projected eigenvalues as a dict of {spin: nd-array}. To access a particular value, you need to do Vasprun.projected_eigenvalues[spin][kpoint index][band index][atom index][orbital_index] This representation is based on actual ordering in VASP and is meant as an intermediate representation to be converted into proper objects. The kpoint, band and atom indices are 0-based (unlike the 1-based indexing in VASP).

projected_magnetisation[source]

Final projected magnetisation as a numpy array with the shape (nkpoints, nbands, natoms, norbitals, 3). Where the last axis is the contribution in the 3 Cartesian directions. This attribute is only set if spin-orbit coupling (LSORBIT = True) or non-collinear magnetism (LNONCOLLINEAR = True) is turned on in the INCAR.

other_dielectric[source]

Dictionary, with the tag comment as key, containing other variants of the real and imaginary part of the dielectric constant (e.g., computed by RPA) in function of the energy (frequency). Optical properties (e.g. absorption coefficient) can be obtained through this. The data is given as a tuple of 3 values containing each of them the energy, the real part tensor, and the imaginary part tensor ([energies],[[real_partxx,real_partyy,real_partzz,real_partxy, real_partyz,real_partxz]],[[imag_partxx,imag_partyy,imag_partzz, imag_partxy, imag_partyz, imag_partxz]])

nionic_steps[source]

The total number of ionic steps. This number is always equal to the total number of steps in the actual run even if ionic_step_skip is used.

force_constants[source]

Force constants computed in phonon DFPT run(IBRION = 8). The data is a 4D numpy array of shape (natoms, natoms, 3, 3).

normalmode_eigenvals[source]

Normal mode frequencies. 1D numpy array of size 3*natoms.

normalmode_eigenvecs[source]

Normal mode eigen vectors. 3D numpy array of shape (3*natoms, natoms, 3).

md_data[source]

Available only for ML MD runs, i.e., INCAR with ML_LMLFF = .TRUE. md_data is a list of dict with the following format:

[

{

‘energy’: {

‘e_0_energy’: -525.07195568, ‘e_fr_energy’: -525.07195568, ‘e_wo_entrp’: -525.07195568, ‘kinetic’: 3.17809233, ‘lattice kinetic’: 0.0, ‘nosekinetic’: 1.323e-05, ‘nosepot’: 0.0, ‘total’: -521.89385012 },

‘forces’: [[0.17677989, 0.48309874, 1.85806696], …], ‘structure’: Structure object

}

]

VASP inputs

incar[source]

Incar object for parameters specified in INCAR file.

parameters[source]

Incar object with parameters that vasp actually used, including all defaults.

kpoints[source]

Kpoints object for KPOINTS specified in run.

actual_kpoints[source]

List of actual kpoints, e.g., [[0.25, 0.125, 0.08333333], [-0.25, 0.125, 0.08333333], [0.25, 0.375, 0.08333333], ….]

actual_kpoints_weights[source]

List of kpoint weights, E.g., [0.04166667, 0.04166667, 0.04166667, 0.04166667, 0.04166667, ….]

atomic_symbols[source]

List of atomic symbols, e.g., [“Li”, “Fe”, “Fe”, “P”, “P”, “P”]

potcar_symbols[source]

List of POTCAR symbols. e.g., [“PAW_PBE Li 17Jan2003”, “PAW_PBE Fe 06Sep2000”, ..]

Author: Shyue Ping Ong

Parameters:

• filename (str) – Filename to parse

• ionic_step_skip (int) – If ionic_step_skip is a number > 1, only every ionic_step_skip ionic steps will be read for structure and energies. This is very useful if you are parsing very large vasprun.xml files and you are not interested in every single ionic step. Note that the final energies may not be the actual final energy in the vasprun.

• ionic_step_offset (int) – Used together with ionic_step_skip. If set, the first ionic step read will be offset by the amount of ionic_step_offset. For example, if you want to start reading every 10th structure but only from the 3rd structure onwards, set ionic_step_skip to 10 and ionic_step_offset to 3. Main use case is when doing statistical structure analysis with extremely long time scale multiple VASP calculations of varying numbers of steps.

• parse_dos (bool) – Whether to parse the dos. Defaults to True. Set to False to shave off significant time from the parsing if you are not interested in getting those data.

• parse_eigen (bool) – Whether to parse the eigenvalues. Defaults to True. Set to False to shave off significant time from the parsing if you are not interested in getting those data.

• parse_projected_eigen (bool) – Whether to parse the projected eigenvalues and magnetisation. Defaults to False. Set to True to obtain projected eigenvalues and magnetisation. Note that this can take an extreme amount of time and memory. So use this wisely.

• parse_potcar_file (bool/str) –

  Whether to parse the potcar file to read the potcar hashes for the potcar_spec attribute. Defaults to True, where no hashes will be determined and the potcar_spec dictionaries will read {“symbol”: ElSymbol, “hash”: None}. By Default, looks in the same directory as the vasprun.xml, with same extensions as

  Vasprun.xml. If a string is provided, looks at that filepath.

• occu_tol (float) – Sets the minimum tol for the determination of the vbm and cbm. Usually the default of 1e-8 works well enough, but there may be pathological cases.

• separate_spins (bool) – Whether the band gap, CBM, and VBM should be reported for each individual spin channel. Defaults to False, which computes the eigenvalue band properties independent of the spin orientation. If True, the calculation must be spin-polarized.

• exception_on_bad_xml (bool) – Whether to throw a ParseException if a malformed XML is detected. Default to True, which ensures only proper vasprun.xml are parsed. You can set to False if you want partial results (e.g., if you are monitoring a calculation during a run), but use the results with care. A warning is issued.

_parse(stream, parse_dos, parse_eigen, parse_projected_eigen)[source]

static _parse_atominfo(elem)[source]

_parse_calculation(elem)[source]

_parse_chemical_shielding_calculation(elem)[source]

static _parse_diel(elem)[source]

static _parse_dos(elem)[source]

static _parse_dynmat(elem)[source]

static _parse_eigen(elem)[source]

static _parse_kpoints(elem)[source]

static _parse_optical_transition(elem)[source]

_parse_params(elem)[source]

static _parse_projected_eigen(elem)[source]

_parse_structure(elem)[source]

as_dict()[source]

JSON-serializable dict representation.

calculate_efermi(tol: float = 0.001)[source]

Calculate the Fermi level using a robust algorithm.

Sometimes VASP can put the Fermi level just inside of a band due to issues in the way band occupancies are handled. This algorithm tries to detect and correct for this bug.

Slightly more details are provided here: https://www.vasp.at/forum/viewtopic.php?f=4&t=17981

property complete_dos[source]

A complete dos object which incorporates the total dos and all projected dos.

property complete_dos_normalized: CompleteDos[source]

A CompleteDos object which incorporates the total DOS and all projected DOS. Normalized by the volume of the unit cell with units of states/eV/unit cell volume.

property converged[source]

Returns: True if a relaxation run is converged both ionically and electronically.

property converged_electronic[source]

Returns: True if electronic step convergence has been reached in the final ionic step.

property converged_ionic[source]

Returns: True if ionic step convergence has been reached, i.e. that vasp exited before reaching the max ionic steps for a relaxation run.

property dielectric[source]

Returns: The real and imaginary part of the dielectric constant (e.g., computed by RPA) in function of the energy (frequency). Optical properties (e.g. absorption coefficient) can be obtained through this. The data is given as a tuple of 3 values containing each of them the energy, the real part tensor, and the imaginary part tensor ([energies],[[real_partxx,real_partyy,real_partzz,real_partxy, real_partyz,real_partxz]],[[imag_partxx,imag_partyy,imag_partzz, imag_partxy, imag_partyz, imag_partxz]]).

property eigenvalue_band_properties[source]

Band properties from the eigenvalues as a tuple, (band gap, cbm, vbm, is_band_gap_direct). In the case of separate_spins=True, the band gap, cbm, vbm, and is_band_gap_direct are each lists of length 2, with index 0 representing the spin-up channel and index 1 representing the spin-down channel.

property epsilon_ionic[source]

Property only available for DFPT calculations and when IBRION=5, 6, 7 or 8.

Returns:

The ionic part of the static dielectric constant. Present when it’s a DFPT run (LEPSILON=TRUE) and IBRION=5, 6, 7 or 8

property epsilonassets[source]

Property only available for DFPT calculations.

Returns:

The static part of the dielectric constant. Present when it’s a DFPT run (LEPSILON=TRUE)

property epsilonassets_wolfe[source]

Property only available for DFPT calculations.

Returns:

The static part of the dielectric constant without any local field effects. Present when it’s a DFPT run (LEPSILON=TRUE)

property final_energy[source]

get_band_structure(kpoints_filename: str | None = None, efermi: float | Literal['smart'] | None = None, line_mode: bool = False, force_hybrid_mode: bool = False) → BandStructureSymmLine | BandStructure[source]

Get the band structure as a BandStructure object.

Parameters:

• kpoints_filename – Full path of the KPOINTS file from which the band structure is generated. If none is provided, the code will try to intelligently determine the appropriate KPOINTS file by substituting the filename of the vasprun.xml with KPOINTS. The latter is the default behavior.

• efermi – The Fermi energy associated with the bandstructure, in eV. By default (None), uses the value reported by VASP in vasprun.xml. To manually set the Fermi energy, pass a float. Pass ‘smart’ to use the calculate_efermi() method, which calculates the Fermi level by first checking whether it lies within a small tolerance (by default 0.001 eV) of a band edge) If it does, the Fermi level is placed in the center of the bandgap. Otherwise, the value is identical to the value reported by VASP.

• line_mode – Force the band structure to be considered as a run along symmetry lines. (Default: False)

• force_hybrid_mode – Makes it possible to read in self-consistent band structure calculations for every type of functional. (Default: False)

Returns:

a BandStructure object (or more specifically a BandStructureSymmLine object if the run is detected to be a run along symmetry lines)

Two types of runs along symmetry lines are accepted: non-sc with Line-Mode in the KPOINT file or hybrid, self-consistent with a uniform grid+a few kpoints along symmetry lines (explicit KPOINTS file) (it’s not possible to run a non-sc band structure with hybrid functionals). The explicit KPOINTS file needs to have data on the kpoint label as commentary.

get_computed_entry(inc_structure=True, parameters=None, data=None, entry_id: str | None = None)[source]

Returns a ComputedEntry or ComputedStructureEntry from the Vasprun.

Parameters:

• inc_structure (bool) – Set to True if you want ComputedStructureEntries to be returned instead of ComputedEntries.

• parameters (list) – Input parameters to include. It has to be one of the properties supported by the Vasprun object. If parameters is None, a default set of parameters that are necessary for typical post-processing will be set.

• data (list) – Output data to include. Has to be one of the properties supported by the Vasprun object.

• entry_id (str) – Specify an entry id for the ComputedEntry. Defaults to “vasprun-{current datetime}”

Returns:

ComputedStructureEntry/ComputedEntry

get_potcars(path)[source]

Parameters:

path – Path to search for POTCARs

Returns:

Potcar from path.

get_trajectory()[source]

This method returns a Trajectory object, which is an alternative representation of self.structures into a single object. Forces are added to the Trajectory as site properties.

Returns: a Trajectory

property hubbards[source]

Hubbard U values used if a vasprun is a GGA+U run. {} otherwise.

property is_hubbard: bool[source]

True if run is a DFT+U run.

property is_spin: bool[source]

True if run is spin-polarized.

property optical_absorption_coeff[source]

Calculate the optical absorption coefficient from the dielectric constants. Note that this method is only implemented for optical properties calculated with GGA and BSE.

Returns:

optical absorption coefficient in list

property run_type[source]

Returns the run type. Currently detects GGA, metaGGA, HF, HSE, B3LYP, and hybrid functionals based on relevant INCAR tags. LDA is assigned if PAW POTCARs are used and no other functional is detected.

Hubbard U terms and vdW corrections are detected automatically as well.

property structures[source]

Returns: List of Structure objects for the structure at each ionic step.

update_charge_from_potcar(path)[source]

Sets the charge of a structure based on the POTCARs found.

Parameters:

path – Path to search for POTCARs

update_potcar_spec(path)[source]

Parameters:

path – Path to search for POTCARs

Returns:

Potcar spec from path.