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: str, fmt: str = 'text') → str[source]

Get help on a VASP tag.

Parameters:

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

Returns:

Help text.

classmethod get_incar_tags() → list[str][source]

Get a list of all INCAR tags from the VASP wiki.

print_help(tag: str) → None[source]

Print the help for a TAG.

Parameters:

tag (str) – Tag used in VASP.

print_jupyter_help(tag: str) → None[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.

exception BadPoscarWarning[source]

Bases: UserWarning

Warning class for bad POSCAR entries.

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

Bases: UserDict, MSONable

A case-insensitive dictionary to read/write INCAR files with additional helper functions.

• Keys are stored in uppercase to allow case-insensitive access (set, get, del, update, setdefault).

• String values are capitalized by default, except for keys specified

  in the lower_str_keys/as_is_str_keys of the proc_val method.

Clean up params and create an Incar object.

Parameters:

params (dict) – INCAR parameters as a dictionary.

Warning

BadIncarWarning: If there are duplicate in keys (case insensitive).

as_dict() → dict[source]

MSONable dict.

check_params() → None[source]

Check INCAR for invalid tags or values. If a tag doesn’t exist, calculation will still run, however VASP will ignore the tag and set it as default without letting you know.

copy() → Self[source]

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

Diff function for Incar. Compare two Incars and indicate 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:

of the following format:

{“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[str, dict]

classmethod from_dict(dct: dict[str, Any]) → Self[source]

Parameters:

dct (dict) – Serialized Incar.

Returns:

Incar

classmethod from_file(filename: PathLike) → Self[source]

Read an Incar object from a file.

Parameters:

filename (str) – Filename for file

Returns:

Incar object

classmethod from_str(string: str) → Self[source]

Read an Incar object from a string.

Parameters:

string (str) – Incar string

Returns:

Incar object

get(key: str, default: Any = None) → Any[source]

Get a value for a case-insensitive key, return default if not found.

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

Get a string representation of the INCAR. Differ from the __str__ method to provide options for pretty printing.

Parameters:

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

• pretty (bool) – Whether to pretty align output. Defaults to False.

static proc_val(key: str, val: str) → list | bool | float | int | str[source]

Helper method to convert INCAR parameters to proper types like ints, floats, lists, etc.

Parameters:

• key (str) – INCAR parameter key.

• val (str) – Value of INCAR parameter.

write_file(filename: PathLike) → None[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[Kpoint] = ((1, 1, 1),), kpts_shift: tuple[float, float, float] = (0, 0, 0), kpts_weights: list[float] | None = None, coord_type: Literal['Reciprocal', 'Cartesian'] | None = None, labels: list[str] | None = None, tet_number: int = 0, tet_weight: float = 0, tet_connections: list[tuple] | None = None)[source]

Bases: MSONable

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

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

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) – 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 (list[float]) – Optional weights 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]), …]

as_dict() → dict[str, Any][source]

MSONable dict.

classmethod automatic(subdivisions: int, comment: str = 'Fully automatic kpoint scheme') → Self[source]

Constructor for a fully automatic Kpoint grid, with Gamma-centered grids and the number of subdivisions along each reciprocal lattice vector determined by the scheme in the VASP manual.

Parameters:

• subdivisions (int) – Number of subdivisions along each reciprocal lattice vector.

• comment (str) – Comment in Kpoints.

Returns:

Kpoints

classmethod automatic_density(structure: Structure | IStructure, kppa: float, force_gamma: bool = False, comment: str | None = None) → Self[source]

Get an automatic Kpoints object based on a structure and a kpoint density. Uses Gamma centered meshes for hexagonal cells and face-centered cells, 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).

• comment (str) – Comment in Kpoints.

Returns:

Kpoints

classmethod automatic_density_by_lengths(structure: Structure | IStructure, length_densities: Sequence[float], force_gamma: bool = False, comment: str | None = None) → Self[source]

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

Algorithm:

For a given dimension, the number 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[float]) – 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.

• comment (str) – Comment in Kpoints.

Returns:

Kpoints

classmethod automatic_density_by_vol(structure: Structure | IStructure, kppvol: int, force_gamma: bool = False, comment: str | None = None) → Self[source]

Get an automatic Kpoints 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.

• comment (str) – Comment in Kpoints.

Returns:

Kpoints

classmethod automatic_gamma_density(structure: Structure | IStructure, kppa: float, comment: str | None = None) → Self[source]

Get an automatic Kpoints 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 (Structure) – Input structure

• kppa (float) – Grid density

• comment (str) – Comment in Kpoints.

classmethod automatic_linemode(divisions: int, ibz: HighSymmKpath, comment: str = 'Line_mode KPOINTS file') → Self[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 (int) – Parameter determining the number of k-points along each high symmetry line.

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

• comment (str) – Comment in Kpoints.

Returns:

Kpoints object

copy() → Self[source]

Make a copy of the Kpoints object.

classmethod from_dict(dct: dict[str, Any]) → Self[source]

Parameters:

dct (dict) – Dict representation.

Returns:

Kpoints

classmethod from_file(filename: PathLike) → Self[source]

Read a Kpoints object from a KPOINTS file.

Parameters:

filename (PathLike) – File to read.

Returns:

Kpoints object

classmethod from_str(string: str) → Self[source]

Reads a Kpoints object from a KPOINTS string.

Parameters:

string (str) – KPOINTS string.

Returns:

Kpoints object

classmethod gamma_automatic(kpts: tuple[int, int, int] = (1, 1, 1), shift: tuple[float, float, float] = (0, 0, 0), comment: str = 'Automatic kpoint scheme') → Self[source]

Construct 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).

• comment (str) – Comment in Kpoints.

Returns:

Kpoints

property kpts: list[Kpoint][source]

A sequence of Kpoints, where each Kpoint is a tuple of 3 or 1.

classmethod monkhorst_automatic(kpts: tuple[int, int, int] = (2, 2, 2), shift: tuple[float, float, float] = (0, 0, 0), comment: str = 'Automatic kpoint scheme') → Self[source]

Construct 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).

• comment (str) – Comment in Kpoints.

Returns:

Kpoints

property style: KpointsSupportedModes[source]

Style for kpoint generation. One of Kpoints_supported_modes enum.

supported_modes[source]

alias of KpointsSupportedModes

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

Write Kpoints to a file.

Parameters:

filename (PathLike) – 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]

classmethod from_str(mode: str) → Self[source]

Parameters:

mode – String.

Returns:

Kpoints_supported_modes

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

Bases: NamedTuple

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

E: float[source]

Alias for field number 3

j: float[source]

Alias for field number 2

l: int[source]

Alias for field number 1

n: int[source]

Alias for field number 0

occ: float[source]

Alias for field number 4

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

Bases: NamedTuple

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

E: float[source]

Alias for field number 1

Rcut: float[source]

Alias for field number 3

Rcut2: float | None[source]

Alias for field number 5

Type: int[source]

Alias for field number 2

Type2: int | None[source]

Alias for field number 4

l: int[source]

Alias for field number 0

exception PmgVaspPspDirError[source]

Bases: ValueError

Error thrown when PMG_VASP_PSP_DIR is not configured, but POTCAR is requested.

class Poscar(structure: Structure | IStructure, 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, lattice_velocities: ArrayLike | None = None, sort_structure: bool = False)[source]

Bases: MSONable

Represent the data in a POSCAR or CONTCAR file.

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 an MD CONTCAR).

predictor_corrector_preamble[source]

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

lattice_velocities[source]

Lattice velocities and current lattice (typically read in from an MD CONTCAR). A 6x3 array of floats.

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.

• lattice_velocities (ArrayLike | None, optional) – Lattice velocities and current lattice for the POSCAR. Available in MD runs with variable cell. 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]

MSONable dict.

classmethod from_dict(dct: dict) → Self[source]

Parameters:

dct (dict) – Dict representation.

Returns:

Poscar

classmethod from_file(filename: PathLike, check_for_potcar: bool = True, read_velocities: bool = True, **kwargs: dict[str, Any]) → Self[source]

Read 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, where a warning would be issued. 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.

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.

classmethod from_str(data: str, default_names: list[str] | None = None, read_velocities: bool = True) → Self[source]

Read 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. This could be used to convert a VASP 4 POSCAR to POSCAR 5/6 format.

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

Returns:

Poscar object.

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

Return a string to be written as a POSCAR file. By default, site symbols are written, which is compatible 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) – Number of significant digits to output all quantities. Defaults to 16. Note that positions are output in fixed point, while velocities are output in scientific format.

Returns:

representation of POSCAR.

Return type:

str

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

Return a string to be written as a POSCAR file. By default, site symbols are written, which is compatible 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) – Number of significant digits to output all quantities. Defaults to 16. Note that positions are output in fixed point, while velocities are output in scientific format.

Returns:

representation of POSCAR.

Return type:

str

property lattice_velocities: ArrayLike | None[source]

Lattice velocities in Poscar (including the current lattice vectors).

property natoms: list[int][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: ArrayLike | None[source]

Predictor corrector in Poscar.

property predictor_corrector_preamble: str | None[source]

Predictor corrector preamble in Poscar.

property selective_dynamics: ArrayLike | None[source]

Selective dynamics in Poscar.

set_temperature(temperature: float) → None[source]

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

Scale 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).

Overwrite imported velocities, if any.

Parameters:

temperature (float) – Temperature in Kelvin.

property site_symbols: list[str][source]

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

property velocities: ArrayLike | None[source]

Velocities in Poscar.

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

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

class Potcar(symbols: Sequence[str] | None = None, functional: str | None = None, sym_potcar_map: dict[str, str] | None = None)[source]

Bases: list, MSONable

Read and write POTCAR files for calculations. Consists of a list of PotcarSingle.

Parameters:

• symbols (list[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: ClassVar[tuple] = ('PBE', 'PBE_52', 'PBE_52_W_HASH', 'PBE_54', 'PBE_54_W_HASH', 'PBE_64', 'LDA', 'LDA_52', 'LDA_52_W_HASH', 'LDA_54', 'LDA_54_W_HASH', 'LDA_64', 'PW91', 'LDA_US', 'PW91_US', 'Perdew_Zunger81')[source]

as_dict() → dict[source]

MSONable dict representation.

classmethod from_dict(dct: dict) → Self[source]

Parameters:

dct (dict) – Dict representation.

Returns:

Potcar

classmethod from_file(filename: str)[source]

Reads Potcar from file.

Parameters:

filename – Filename

Returns:

Potcar

classmethod from_spec(potcar_spec: list[dict], functionals: list[str] | None = None) → Potcar[source]

Generate a POTCAR from a list of POTCAR spec dicts.

If a set of POTCARs for the same functional cannot be found, raises a ValueError. :param potcar_spec: list[dict]

List of POTCAR specs, from Potcar.spec or [PotcarSingle.spec]

Parameters:

functionals – list[str] or None (default) If a list of strings, the functionals to restrict the search to.

Returns:

Potcar, a POTCAR using a single functional that matches the input spec.

classmethod from_str(data: str)[source]

Read Potcar from a string.

Parameters:

data – Potcar as a string.

Returns:

Potcar

set_symbols(symbols: Sequence[str], functional: str | None = None, sym_potcar_map: dict[str, str] | None = None) → 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 (list[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 to 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: list[dict][source]

POTCAR spec for all POTCARs in this instance.

Parameters:

extra_spec – Sequence[str] or None (default) A list of extra POTCAR fields to include in the spec. If None, defaults to [“symbol”] (needed for compatibility with LOBSTER).

Returns:

list[dict], a list of PotcarSingle.spec dicts

property symbols: list[str][source]

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

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

Write Potcar to a file.

Parameters:

filename (PathLike) – filename to write to.

write_potcar_spec(filename: str = 'POTCAR.spec.json.gz') → None[source]

Write POTCAR spec to file.

Parameters:

filename – str = “POTCAR.spec.json.gz” The name of a file to write the POTCAR spec to.

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

Bases: object

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

data[source]

POTCAR data as a string.

Type:

str

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.

Type:

dict

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 validation fails.

Parameters:

• data (str) – Complete, single and raw POTCAR file as a string.

• symbol (str) – 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, but is not always reliable!

property atomic_no: int[source]

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

static compare_potcar_stats(potcar_stats_1: dict, potcar_stats_2: dict, tolerance: float = 1e-06, check_potcar_fields: Sequence[str] = ['header', 'data']) → bool[source]

Compare PotcarSingle._summary_stats to assess if they are the same within a tolerance.

Parameters:

• potcar_stats_1 – dict Dict of potcar summary stats from the first PotcarSingle, from the PotcarSingle._summary stats attr

• potcar_stats_2 – dict Second dict of summary stats

• tolerance – float = 1.e-6 Tolerance to assess equality of numeric statistical values

• check_potcar_fields – Sequence[str] = [“header”, “data”] The specific fields of the POTCAR to check, whether just the “header”, just the “data”, or both

Returns:

bool

Whether the POTCARs are identical according to their summary stats.

copy() → Self[source]

Return a copy of the PotcarSingle.

Returns:

PotcarSingle

property electron_configuration: list[tuple[int, str, float]][source]

Valence electronic configuration corresponding to the ZVAL, read from the “Atomic configuration” section of POTCAR.

Returns:

A list of tuples containing:

• n (int): Principal quantum number.

• subshell (str): Subshell notation (s, p, d, f).

• occ (float): Occupation number, limited to ZVAL.

Return type:

list[tuple[int, str, float]]

property element: str[source]

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

classmethod from_file(filename: PathLike) → Self[source]

Read PotcarSingle from file.

Parameters:

filename – Filename.

Returns:

PotcarSingle

classmethod from_symbol_and_functional(symbol: str, functional: str | None = None) → Self[source]

Make a PotcarSingle from a symbol and functional.

Parameters:

• symbol (str) – Symbol, e.g. Li_sv

• functional (str) – Functional, e.g. PBE

Returns:

PotcarSingle

property functional: str | None[source]

Functional associated with PotcarSingle.

property functional_class: str | None[source]

Functional class associated with PotcarSingle.

functional_dir: ClassVar[dict[str, str]] = {'LDA': 'POT_LDA_PAW', 'LDA_52': 'POT_LDA_PAW_52', 'LDA_52_W_HASH': 'POTPAW_LDA_52', 'LDA_54': 'POT_LDA_PAW_54', 'LDA_54_W_HASH': 'POTPAW_LDA_54', 'LDA_64': 'POT_LDA_PAW_64', 'LDA_US': 'POT_LDA_US', 'PBE': 'POT_GGA_PAW_PBE', 'PBE_52': 'POT_GGA_PAW_PBE_52', 'PBE_52_W_HASH': 'POTPAW_PBE_52', 'PBE_54': 'POT_GGA_PAW_PBE_54', 'PBE_54_W_HASH': 'POTPAW_PBE_54', 'PBE_64': 'POT_PAW_PBE_64', 'PW91': 'POT_GGA_PAW_PW91', 'PW91_US': 'POT_GGA_US_PW91', 'Perdew_Zunger81': 'POT_LDA_PAW'}[source]

functional_tags: ClassVar[dict[str, dict[Literal['name', 'class'], str]]] = {'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_electron_configuration(tol: float = 0.01) → list[tuple[int, str, float]][source]

Valence electronic configuration corresponding to the ZVAL, read from the “Atomic configuration” section of POTCAR.

Parameters:

tol (float) –

Tolerance for occupation numbers. - Orbitals with an occupation below tol are considered empty. - Accumulation of electrons stops once the total occupation

reaches ZVAL - tol, preventing unnecessary additions.

Returns:

A list of tuples containing:

• n (int): Principal quantum number.

• subshell (str): Subshell notation (s, p, d, f).

• occ (float): Occupation number, limited to ZVAL.

Return type:

list[tuple[int, str, float]]

property hash_sha256_from_file: str | None[source]

SHA256 hash of the POTCAR file as read from the file. None if no SHA256 hash is found.

identify_potcar(mode: Literal['data', 'file'] = 'data', data_tol: float = 1e-06) → tuple[list[str], list[str]][source]

Identify the symbol and compatible functionals associated with this PotcarSingle.

This method checks the summary statistics of either the POTCAR metadadata (PotcarSingle._summary_stats[key][“header”] for key in (“keywords”, “stats”) ) or the entire POTCAR file (PotcarSingle._summary_stats) against a database of hashes for POTCARs distributed with VASP 5.4.4.

Parameters:

• mode ("data" or "file") – “data” mode checks the POTCAR header keywords and stats only while “file” mode checks the entire summary stats.

• data_tol (float) – Tolerance for comparing the summary statistics of the POTCAR with the reference statistics.

Returns:

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

the PotcarSingle

Return type:

symbol (list)

identify_potcar_hash_based(mode: Literal['data', 'file'] = 'data') → tuple[list[str], list[str]][source]

Identify the symbol and compatible functionals associated with this PotcarSingle.

This method checks the MD5 hash of either the POTCAR metadadata (PotcarSingle.md5_header_hash) or the entire POTCAR file (PotcarSingle.md5_computed_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.keywords, 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 is_valid: bool[source]

Check that POTCAR matches reference metadata. Parsed metadata is stored in self._summary_stats as a human-readable dict,

self._summary_stats = {

“keywords”: {

“header”: list[str], “data”: list[str],

}, “stats”: {

“header”: dict[float], “data”: dict[float],

},

}.

Rationale:

Each POTCAR is structured as

Header (self.keywords) Data (actual pseudopotential values in data blocks)

For the Data block of POTCAR, there are unformatted data blocks of unknown length and contents/data type, e.g. you might see

<float> <bool> <Data Keyword> <int> <int> <float> <float> … <float> <Data Keyword> <float> … <float>

but this is impossible to process algorithmically without a full POTCAR schema. Note also that POTCARs can contain different data keywords

All keywords found in the header, essentially self.keywords, and the data block (<Data Keyword> above) are stored in self._summary_stats[“keywords”]

To avoid issues of copyright, statistics (mean, mean of abs vals, variance, max, min) for the numeric values in the header and data sections of POTCAR are stored in self._summary_stats[“stats”]

tol is then used to match statistical values within a tolerance

property md5_computed_file_hash: str[source]

MD5 hash of the entire PotcarSingle.

property md5_header_hash: str[source]

MD5 hash of the metadata defining the PotcarSingle.

property nelectrons: float[source]

Number of electrons.

parse_functions: ClassVar[dict[str, Any]] = {'COPYR': <method 'strip' of 'str' objects>, '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': <method 'strip' of 'str' objects>, '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': <method 'strip' of 'str' objects>, 'STEP': <function _parse_list>, 'TITEL': <method 'strip' of 'str' objects>, 'VRHFIN': <method 'strip' of 'str' objects>, 'ZVAL': <function _parse_float>}[source]

property potential_type: Literal['NC', 'PAW', 'US'][source]

NC (Norm-conserving), US (Ultra-soft), PAW (Projector augmented wave).

Type:

Type of PSP

property sha256_computed_file_hash: str[source]

Compute a SHA256 hash of the PotcarSingle EXCLUDING lines starting with ‘SHA256’ and ‘COPYR’.

spec(extra_spec: Sequence[str] | None = None) → dict[str, Any][source]

POTCAR spec used in vasprun.xml.

Parameters:

extra_spec – Sequence[str] or None (default) A list of extra POTCAR fields to include in the spec. If None, defaults to no extra spec.

Returns:

dict of POTCAR spec

property symbol: str[source]

The POTCAR symbol, e.g. W_pv.

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

Attempt 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:

has_sha256 and passed_hash_check.

Return type:

tuple[bool, bool]

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

Write PotcarSingle to a file.

Parameters:

filename (str) – File to write to.

exception UnknownPotcarWarning[source]

Bases: UserWarning

Warning raised when POTCAR hashes do not pass validation.

class VaspInput(incar: dict | Incar, kpoints: Kpoints | None, poscar: Poscar, potcar: Potcar | str | None, potcar_spec: bool = False, optional_files: dict[PathLike, object] | None = None, **kwargs)[source]

Bases: dict, MSONable

Contain a set of VASP input objects corresponding to a run.

Initialize 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 or str) – The Potcar object.

• potcar_spec (bool = False) – used to share POTCAR info without license issues. True –> POTCAR is a list of symbols, write POTCAR.spec False –> POTCAR is a VASP POTCAR, write POTCAR

• 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() → dict[source]

MSONable dict.

copy(deep: bool = True) → Self[source]

Deep copy of VaspInput.

classmethod from_dict(dct: dict) → Self[source]

Parameters:

dct (dict) – Dict representation.

Returns:

VaspInput

classmethod from_directory(input_dir: PathLike, optional_files: dict | None = None) → Self[source]

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

Parameters:

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

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

property incar: Incar[source]

INCAR object.

property kpoints: Kpoints | None[source]

KPOINTS object.

property poscar: Poscar[source]

POSCAR object.

property potcar: Potcar | str | None[source]

POTCAR or POTCAR.spec object.

run_vasp(run_dir: PathLike = '.', vasp_cmd: list | None = None, output_file: PathLike = 'vasp.out', err_file: PathLike = 'vasp.err') → None[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: PathLike = '.', make_dir_if_not_present: bool = True, cif_name: str | None = None, zip_name: str | None = None, files_to_transfer: dict | None = None) → None[source]

Write VASP inputs to a directory.

Parameters:

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

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

• cif_name (str or None) – If a str, the name of the CIF file to write the POSCAR to (the POSCAR will also be written).

• zip_name (str or None) – If a str, the name of the zip to archive the VASP input set to.

• files_to_transfer (dict) –

  A dictionary of

  { < input filename >: < output filepath >}.

  This allows the transfer of < input filename > files from a previous calculation to < output filepath >.

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

Post-process 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: PathLike) → Self[source]

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

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

Construct a DielectricFunction from Vasprun, Kpoint, and Waveder.

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 looking 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: NDArray, ismear: int) → NDArray[source]

Replication of VASP’s delta function.

delta_methfessel_paxton(x: NDArray, n: int) → NDArray[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) → tuple[NDArray, NDArray][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.ndarray

get_delta(x0: float, sigma: float, nx: int, dx: float, ismear: int = 3) → NDArray[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.ndarray

get_step(x0: float, sigma: float, nx: int, dx: float, ismear: int) → float[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.ndarray

kramers_kronig(eps: 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.ndarray

step_func(x: NDArray, ismear: int) → NDArray[source]

Replication of VASP’s step function.

step_methfessel_paxton(x: NDArray, n: int) → NDArray[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: PathLike, 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() → dict[source]

JSON-serializable dict representation.

class BandgapProps(vbm: 'float | None' = None, cbm: 'float | None' = None, direct_gap_eigenvalues: 'tuple[float, float] | None' = None, efermi: 'float | None' = None, vbm_k: 'tuple[float, float, float] | None' = None, cbm_k: 'tuple[float, float, float] | None' = None, direct_gap_k: 'tuple[float, float, float] | None' = None)[source]

Bases: MSONable

cbm: float | None = None[source]

cbm_k: tuple[float, float, float] | None = None[source]

direct_gap_eigenvalues: tuple[float, float] | None = None[source]

direct_gap_k: tuple[float, float, float] | None = None[source]

efermi: float | None = None[source]

vbm: float | None = None[source]

vbm_k: tuple[float, float, float] | None = None[source]

class Chgcar(poscar: Poscar | Structure, data: dict[str, NDArray], data_aug: NDArray | None = None)[source]

Bases: VolumetricData

CHGCAR file reader.

Parameters:

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

• data – Actual data.

• data_aug – Augmentation charge data.

classmethod from_file(filename: str) → Self[source]

Read a CHGCAR file.

Parameters:

filename (str) – Path to CHGCAR file.

Returns:

Chgcar

property net_magnetization: float | None[source]

Net magnetic moment from Chgcar.

class Dynmat(filename: PathLike)[source]

Bases: object

DYNMAT file reader.

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

Type:

dict

Authors: Patrick Huck

Parameters:

filename – Name of file containing DYNMAT.

get_phonon_frequencies() → list[float][source]

Calculate phonon frequencies.

WARNING: This method is most likely incorrect or suboptimal,

hence for demonstration purposes only.

Returns:

phonon frequencies.

Return type:

list[float]

property masses: list[float][source]

The list of atomic masses.

property natoms: int[source]

The number of atoms.

property ndisps: int[source]

The number of displacements.

property nspecs: int[source]

The number of species.