pymatgen.io namespace

Subpackages

Submodules

pymatgen.io.adf module

IO for ADF files.

class AdfInput(task)[source]

Bases: object

A basic ADF input file writer.

Initialization method.

Parameters:

task (AdfTask) – An ADF task.

write_file(molecule, inp_file)[source]

Write an ADF input file.

Parameters:

  • molecule (Molecule) – The molecule for this task.

  • inpfile (str) – The name where the input file will be saved.

exception AdfInputError[source]

Bases: Exception

The default error class for ADF.

class AdfKey(name, options=None, subkeys=None)[source]

Bases: MSONable

The basic input unit for ADF. A key is a string of characters that does not contain a delimiter (blank, comma or equal sign). A key may have multiple subkeys and a set of options.

Initialization method.

Parameters:

  • name (str) – The name of this key.

  • options – Sized The options for this key. Each element can be a primitive object or a tuple/list with two elements: the first is the name and the second is a primitive object.

  • subkeys (Sized) – The subkeys for this key.

Raises:

ValueError – If elements in subkeys are not AdfKey objects.

add_option(option)[source]

Add a new option to this key.

Parameters:

option – Sized or str or int or float A new option to add. This must have the same format with existing options.

Raises:

TypeError – If the format of the given option is different.

add_subkey(subkey)[source]

Add a new subkey to this key.

Parameters:

subkey (AdfKey) – A new subkey.

Notes

Duplicate check will not be performed if this is an ‘Atoms’ block.

as_dict()[source]

A JSON-serializable dict representation of self.

block_keys = ('SCF', 'GEOMETRY', 'XC', 'UNITS', 'ATOMS', 'CHARGE', 'BASIS', 'SYMMETRY', 'RELATIVISTIC', 'OCCUPATIONS', 'SAVE', 'A1FIT', 'INTEGRATION', 'UNRESTRICTED', 'ZLMFIT', 'TITLE', 'EXACTDENSITY', 'TOTALENERGY', 'ANALYTICALFREQ')[source]
classmethod from_dict(dct: dict) → Self[source]

Construct a MSONable AdfKey object from the JSON dict.

Parameters:

dct (dict) – A dict of saved attributes.

Returns:

An AdfKey object recovered from the JSON dict.

Return type:

AdfKey

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

Construct an AdfKey object from the string.

Parameters:

string – str

Returns:

An AdfKey object recovered from the string.

Raises:

ValueError – Currently nested subkeys are not supported. If subend was found a ValueError would be raised.

Notes

Only the first block key will be returned.

has_option(option: str) → bool[source]
Parameters:

option (str) – The option.

Returns:

True if this AdfKey has the given option.

Return type:

bool

has_subkey(subkey: str | AdfKey) → bool[source]
Parameters:

subkey (str | AdfKey) – A key name or AdfKey object.

Returns:

True if this key contains the given subkey.

Return type:

bool

is_block_key() → bool[source]

Return True if this key is a block key.

property key: str[source]

The name of this key. If this is a block key, the name will be converted to upper cases.

remove_option(option: str | int) → None[source]

Remove an option.

Parameters:

option (str | int) – The name or index of the option to remove.

Raises:

TypeError – If the option has a wrong type.

remove_subkey(subkey)[source]

Remove the given subkey, if existed, from this AdfKey.

Parameters:

subkey (str or AdfKey) – The subkey to remove.

sub_keys = ('AtomDepQuality',)[source]
class AdfOutput(filename)[source]

Bases: object

A basic ADF output file parser.

is_failed[source]

Whether the ADF job is failed.

Type:

bool

is_internal_crash[source]

Whether the job crashed. Please read ‘TAPE13’ of the ADF manual for more detail.

Type:

bool

error[source]

The error description.

Type:

str

run_type[source]

The RunType of this ADF job. Possible options are: ‘SinglePoint’, ‘GeometryOptimization’, ‘AnalyticalFreq’ and ‘NUmericalFreq’.

Type:

str

final_energy[source]

The final molecule energy (a.u).

Type:

float

final_structure[source]

The final structure of the molecule.

Type:

GMolecule

energies[source]

The energy of each cycle.

Type:

Sized

structures[source]

The structure of each cycle If geometry optimization is performed.

Type:

Sized

frequencies[source]

The frequencies of the molecule.

Type:

array_like

normal_modes[source]

The normal modes of the molecule.

Type:

array_like

freq_type[source]

Either ‘Analytical’ or ‘Numerical’.

Type:

syr

Initialization method.

Parameters:

filename (str) – The ADF output file to parse.

exception AdfOutputError[source]

Bases: Exception

The default error class for errors raised by AdfOutput.

class AdfTask(operation='energy', basis_set=None, xc=None, title='ADF_RUN', units=None, geo_subkeys=None, scf=None, other_directives=None)[source]

Bases: MSONable

Basic task for ADF. All settings in this class are independent of molecules.

Notes

Unlike other quantum chemistry packages (NWChem, Gaussian, …), ADF does not support calculating force/gradient.

Initialization method.

Parameters:

  • operation (str) – The target operation.

  • basis_set (AdfKey) – The basis set definitions for this task. Defaults to ‘DZ/Large’.

  • xc (AdfKey) – The exchange-correlation functionals. Defaults to PBE.

  • title (str) – The title of this ADF task.

  • units (AdfKey) – The units. Defaults to Angstroms/Degree.

  • geo_subkeys (Sized) – The subkeys for the block key ‘GEOMETRY’.

  • scf (AdfKey) – The scf options.

  • other_directives (Sized) – User-defined directives.

as_dict()[source]

A JSON-serializable dict representation of self.

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

Construct a MSONable AdfTask object from the JSON dict.

Parameters:

dct – A dict of saved attributes.

Returns:

An AdfTask object recovered from the JSON dict d.

static get_default_basis_set()[source]

Get Default basis set.

static get_default_geo()[source]

Get ADFKey using default geometry.

static get_default_scf()[source]

Get ADF using default SCF.

static get_default_units()[source]

Get Default units.

static get_default_xc()[source]

Get ADFKey using default XC.

operations: ClassVar[dict[str, str]] = {'energy': 'Evaluate the single point energy.', 'freq': 'Same as frequencies.', 'frequencies': 'Compute second derivatives and print out an analysis of molecular vibrations.', 'numerical_frequencies': 'Compute molecular frequencies using numerical method.', 'optimize': 'Minimize the energy by varying the molecular structure.'}[source]

pymatgen.io.ase module

This module provides conversion between the Atomic Simulation Environment (ASE) Atoms object and pymatgen Structure objects.

class AseAtomsAdaptor[source]

Bases: object

Adaptor serves as a bridge between ASE Atoms and pymatgen objects.

static get_atoms(structure: SiteCollection, msonable: bool = True, **kwargs) → MSONAtoms | Atoms[source]

Get ASE Atoms object from pymatgen structure or molecule.

Parameters:

  • structure (SiteCollection) – pymatgen Structure or Molecule

  • msonable (bool) – Whether to return an MSONAtoms object, which is MSONable.

  • **kwargs – passed to the ASE Atoms constructor

Returns:

ASE Atoms object

Return type:

Atoms

static get_molecule(atoms: ~pymatgen.io.ase.Atoms, cls: type[~pymatgen.io.ase.MolT] = <class 'pymatgen.core.structure.Molecule'>, **cls_kwargs) → MolT[source]

Get pymatgen molecule from ASE Atoms.

Parameters:

  • atoms (Atom) – ASE Atoms object

  • cls – The molecule class to instantiate (defaults to pymatgen Molecule)

  • **cls_kwargs – Any additional kwargs to pass to the cls constructor

Returns:

Equivalent pymatgen (I)Molecule

Return type:

(I)Molecule

static get_structure(atoms: ~pymatgen.io.ase.Atoms, cls: type[~pymatgen.io.ase.StructT] = <class 'pymatgen.core.structure.Structure'>, **cls_kwargs) → StructT[source]

Get pymatgen structure from ASE Atoms.

Parameters:

  • atoms (Atoms) – ASE Atoms object

  • cls – The structure class to instantiate (defaults to pymatgen Structure)

  • **cls_kwargs – Any additional kwargs to pass to the cls constructor

Returns:

Equivalent pymatgen (I)Structure/(I)Molecule

Return type:

(I)Structure/(I)Molecule

class Atoms(*args, **kwargs)[source]

Bases: object

class MSONAtoms(*args, **kwargs)[source]

Bases: Atoms, MSONable

A custom subclass of ASE Atoms that is MSONable, including .as_dict() and .from_dict() methods.

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

A JSON serializable dict representation of an object.

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

d – Dict representation.

Returns:

MSONable class.

pymatgen.io.atat module

Classes for reading/writing mcsqs files following the rndstr.in format.

class Mcsqs(structure: Structure | IStructure)[source]

Bases: object

Handle input/output for the crystal definition format used by mcsqs and other ATAT codes.

Parameters:

Structure – input Structure.

static structure_from_str(data)[source]

Parses a rndstr.in, lat.in or bestsqs.out file into pymatgen’s Structure format.

Parameters:

data – contents of a rndstr.in, lat.in or bestsqs.out file

Returns:

Structure object

to_str()[source]
Returns:

a structure in mcsqs rndstr.in format.

Return type:

str

pymatgen.io.babel module

OpenBabel interface module, which opens up access to the hundreds of file formats supported by OpenBabel. Requires openbabel with python bindings to be installed. Please consult the openbabel docs https://openbabel.org.

class BabelMolAdaptor(mol: Molecule | openbabel.OBMol | pybel.Molecule)[source]

Bases: object

Adaptor serves as a bridge between OpenBabel’s Molecule and pymatgen’s Molecule.

Initialize with pymatgen Molecule or OpenBabel’s OBMol.

Parameters:

mol – pymatgen’s Molecule/IMolecule or OpenBabel OBMol

add_hydrogen() → None[source]

Add hydrogens (make all hydrogen explicit).

confab_conformers(forcefield: str = 'mmff94', freeze_atoms: list[int] | None = None, rmsd_cutoff: float = 0.5, energy_cutoff: float = 50.0, conf_cutoff: int = 100000, verbose: bool = False) → list[Molecule][source]

Conformer generation based on Confab to generate all diverse low-energy conformers for molecules. This is different from rotor_conformer or gen3d_conformer as it aims to not simply to find a low energy conformation but to generate several different conformations.

Parameters:

  • forcefield (str) – Default is mmff94. Options are ‘gaff’, ‘ghemical’, ‘mmff94’, ‘mmff94s’, and ‘uff’.

  • freeze_atoms ([int]) – index of atoms to be freezed when performing conformer search, default is None.

  • rmsd_cutoff (float) – rmsd_cufoff, default is 0.5 Angstrom.

  • energy_cutoff (float) – energy_cutoff, default is 50.0 kcal/mol.

  • conf_cutoff (int) – max number of conformers to test, default is 1 million.

  • verbose (bool) – whether to display information on torsions found, default is False.

Returns:

Molecule objects for generated conformers.

Return type:

list[Molecule]

classmethod from_file(filename: str, file_format: str = 'xyz', return_all_molecules: bool = False) → Self | list[Self][source]

Uses OpenBabel to read a molecule from a file in all supported formats.

Parameters:

  • filename – Filename of input file

  • file_format – String specifying any OpenBabel supported formats.

  • return_all_molecules – If True, will return a list of BabelMolAdaptor instances, one for each molecule found in the file. If False, will return only the first molecule.

Returns:

BabelMolAdaptor object or list thereof

classmethod from_molecule_graph(mol: MoleculeGraph) → Self[source]

Read a molecule from a pymatgen MoleculeGraph object.

Parameters:

mol – pymatgen MoleculeGraph object.

Returns:

BabelMolAdaptor object

classmethod from_str(string_data: str, file_format: str = 'xyz') → Self[source]

Uses OpenBabel to read a molecule from a string in all supported formats.

Parameters:

  • string_data – String containing molecule data.

  • file_format – String specifying any OpenBabel supported formats.

Returns:

BabelMolAdaptor object

gen3d_conformer() → None[source]

A combined method to first generate 3D structures from 0D or 2D structures and then find the minimum energy conformer:

  1. Use OBBuilder to create a 3D structure using rules and ring templates

  2. Do 250 steps of a steepest descent geometry optimization with the MMFF94 forcefield

  3. Do 200 iterations of a Weighted Rotor conformational search (optimizing each conformer with 25 steps of a steepest descent)

  4. Do 250 steps of a conjugate gradient geometry optimization.

Warning from openbabel docs: For many applications where 100s if not 1000s of molecules need to be processed, gen3d is rather SLOW. Sometimes this function can cause a segmentation fault. A future version of Open Babel will provide options for slow/medium/fast 3D structure generation which will involve different compromises between speed and finding the global energy minimum.

localopt(forcefield: str = 'mmff94', steps: int = 500) → None[source]

A wrapper to pybel’s localopt method to optimize a Molecule.

Parameters:

  • forcefield – Default is mmff94. Options are ‘gaff’, ‘ghemical’, ‘mmff94’, ‘mmff94s’, and ‘uff’.

  • steps – Default is 500.

make3d(forcefield: str = 'mmff94', steps: int = 50) → None[source]

A wrapper to pybel’s make3D method generate a 3D structure from a 2D or 0D structure. The 3D structure is made very quickly using a combination of rules (e.g. sp3 atoms should have four bonds arranged in a tetrahedron) and ring templates (e.g. cyclohexane is shaped like a chair). Once 3D coordinates are generated, hydrogens are added and a quick local optimization is carried out as default.

The generated 3D structure can have clashes or have high energy structures due to some strain. Please consider to use the conformer search or geometry optimization to further optimize the structure.

Parameters:

  • forcefield – Default is mmff94. Options are ‘gaff’, ‘ghemical’, ‘mmff94’, ‘mmff94s’, and ‘uff’.

  • steps – Default is 50.

property openbabel_mol[source]

OpenBabel’s OBMol.

property pybel_mol: Molecule[source]

Pybel’s Molecule object.

property pymatgen_mol: Molecule[source]

Pymatgen Molecule object.

remove_bond(idx1: int, idx2: int) → None[source]

Remove a bond from an openbabel molecule.

Parameters:

  • idx1 – The atom index of one of the atoms participating the in bond

  • idx2 – The atom index of the other atom participating in the bond

rotor_conformer(*rotor_args, algo: str = 'WeightedRotorSearch', forcefield: str = 'mmff94') → None[source]

Conformer search based on several Rotor Search algorithms of openbabel. If the input molecule is not 3D, make3d will be called (generate 3D structure, add hydrogen, a quick localopt). All hydrogen atoms need to be made explicit.

Parameters:

  • rotor_args – pass args to Rotor Search in openbabel. for “WeightedRotorSearch”: (conformers, geomSteps, sampleRingBonds-default False) for “SystematicRotorSearch”: (geomSteps-default 2500, sampleRingBonds-default False) for “RandomRotorSearch”: (conformers, geomSteps-default 2500, sampleRingBonds-default False)

  • algo (str) – Default is “WeightedRotorSearch”. Options are “SystematicRotorSearch”, “RandomRotorSearch”, and “WeightedRotorSearch”.

  • forcefield (str) – Default is mmff94. Options are ‘gaff’, ‘ghemical’, ‘mmff94’, ‘mmff94s’, and ‘uff’.

write_file(filename: str, file_format: str = 'xyz') → None[source]

Uses OpenBabel to output all supported formats.

Parameters:

  • filename – Filename of file to output

  • file_format – String specifying any OpenBabel supported formats.

pymatgen.io.cif module

Classes for Cif input and output from Structures.

class CifBlock(data: dict, loops: list[list[str]], header: str)[source]

Bases: object

Object for storing CIF data. All data is stored in a single dictionary. Data inside loops are stored in lists in the data dictionary, and information on which keys are grouped together are stored in the loops attribute.

Parameters:

  • data – dict of data to go into the CIF. Values should be convertible to string, or lists of these if the key is in a loop

  • loops – list of lists of keys, grouped by which loop they should appear in

  • header – name of the block (appears after the data_ on the first line).

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

Read CifBlock from string.

Parameters:

string – String representation.

Returns:

CifBlock

max_len = 70[source]
class CifFile(data: dict[str, CifBlock], orig_string: str | None = None, comment: str | None = None)[source]

Bases: object

Read and parse CifBlocks from a .cif file or string.

Parameters:

  • data (dict) – Of CifBlock objects.

  • orig_string (str) – The original CIF.

  • comment (str) – Comment.

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

Read CifFile from a filename.

Parameters:

filename – Filename

Returns:

CifFile

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

Read CifFile from a string.

Parameters:

string – String representation.

Returns:

CifFile

class CifParser(filename: PathLike | StringIO, occupancy_tolerance: float = 1.0, site_tolerance: float = 0.0001, frac_tolerance: float = 0.0001, check_cif: bool = True, comp_tol: float = 0.01)[source]

Bases: object

CIF file parser. Attempt to fix CIFs that are out-of-spec, but will issue warnings if corrections applied. These are also stored in the CifParser’s warnings attribute. CIF file parser. Attempt to fix CIFs that are out-of-spec, but will issue warnings if corrections applied. These are also stored in the CifParser’s errors attribute.

Parameters:

  • filename (PathLike) – CIF file, gzipped or bzipped CIF files are fine too.

  • occupancy_tolerance (float) – If total occupancy of a site is between 1 and occupancy_tolerance, it will be scaled down to 1.

  • site_tolerance (float) – This tolerance is used to determine if two sites are at the same position, in which case they will be combined to a single disordered site. Defaults to 1e-4.

  • frac_tolerance (float) – This tolerance is used to determine is a coordinate should be rounded to an ideal value. e.g. 0.6667 is rounded to 2/3. This is desired if symmetry operations are going to be applied. However, for very large CIF files, this may need to be set to 0.

  • check_cif (bool) – Whether to check that stoichiometry reported in CIF matches that of resulting Structure, and whether elements are missing. Defaults to True.

  • comp_tol (float) – Tolerance for how closely stoichiometries of CIF file and pymatgen should match. Defaults to 0.01. Context: Experimental CIF files often don’t report hydrogens positions due to being hard-to-locate with X-rays. pymatgen warns if the stoichiometry of the CIF file and the Structure don’t match to within comp_tol.

as_dict() → dict[source]

MSONable dict.

check(structure: Structure) → str | None[source]

Check whether a Structure created from CIF passes sanity checks.

Checks:

  • Composition from CIF is valid

  • CIF composition contains only valid elements

  • CIF and structure contain the same elements (often hydrogens

    are omitted from CIFs, as their positions cannot be determined from X-ray diffraction, needs more difficult neutron diffraction)

  • CIF and structure have same relative stoichiometry. Thus

    if CIF reports stoichiometry LiFeO, and the structure has composition (LiFeO)4, this check passes.

Parameters:

structure (Structure) – Structure created from CIF.

Returns:

If any check fails, return a human-readable str for the

reason (e.g., which elements are missing). None if all checks pass.

Return type:

str | None

classmethod from_str(cif_string: str, **kwargs) → Self[source]

Create a CifParser from a string.

Parameters:

cif_string (str) – String representation of a CIF.

Returns:

CifParser

get_bibtex_string() → str[source]

Get BibTeX reference from CIF file.

Returns:

BibTeX string.

get_lattice(data: CifBlock, length_strings=('a', 'b', 'c'), angle_strings=('alpha', 'beta', 'gamma'), lattice_type=None) → Lattice | None[source]

Generate the lattice from the provided lattice parameters. In the absence of all six lattice parameters, the crystal system and necessary parameters are parsed.

static get_lattice_no_exception(data: CifBlock, length_strings: tuple[str, str, str] = ('a', 'b', 'c'), angle_strings: tuple[str, str, str] = ('alpha', 'beta', 'gamma'), lattice_type: str | None = None) → Lattice[source]

Convert a CifBlock to a pymatgen Lattice.

Parameters:

  • data – a dictionary of the CIF file

  • length_strings – The strings that are used to identify the length parameters in the CIF file.

  • angle_strings – The strings that are used to identify the angles in the CIF file.

  • lattice_type (str) – The type of lattice.

Returns:

Lattice object

get_magsymops(data: CifBlock) → list[MagSymmOp][source]

Equivalent to get_symops except for magnetic symmetry groups. Separate function since additional operation for time reversal symmetry (which changes magnetic moments on sites) needs to be returned.

get_structures(*args, **kwargs) → list[Structure][source]

Deprecated, use parse_structures instead. Only difference between these two methods is the default primitive=False in parse_structures. So parse_structures(primitive=True) is equivalent to the default behaviour of get_structures().

get_symops(data: CifBlock) → list[SymmOp][source]

Get the symmetry operations, in order to generate symmetry equivalent positions. If no symops are present, the space group symbol is parsed, and symops are generated.

property has_errors: bool[source]

Whether there are errors/warnings detected in CIF parsing.

parse_structures(primitive: bool | None = None, symmetrized: bool = False, check_occu: bool = True, on_error: Literal['ignore', 'warn', 'raise'] = 'warn') → list[Structure][source]

Return list of structures in CIF file.

Parameters:

  • primitive (bool) – Whether to return primitive unit cells. Defaults to False. With magnetic CIF files, will return primitive magnetic cell which may be larger than nuclear primitive cell.

  • symmetrized (bool) – Whether to return a SymmetrizedStructure which will include the equivalent indices and symmetry operations used to create the Structure as provided by the CIF (if explicit symmetry operations are included in the CIF) or generated from information in the CIF (if only space group labels are provided). Note that currently Wyckoff labels and space group labels or numbers are not included in the generated SymmetrizedStructure, these will be notated as “Not Parsed” or -1 respectively.

  • check_occu (bool) – Whether to check site for unphysical occupancy > 1. Useful for experimental results in which occupancy was allowed to refine to unphysical values. Warning: unphysical occupancies are incompatible with many pymatgen features. Defaults to True.

  • on_error ("ignore" | "warn" | "raise") – What to do in case of KeyError or ValueError while parsing CIF file. Defaults to “warn”.

Returns:

All structures in CIF file.

Return type:

list[Structure]

class CifWriter(struct: Structure | IStructure, symprec: float | None = None, write_magmoms: bool = False, significant_figures: int = 8, angle_tolerance: float = 5, refine_struct: bool = True, write_site_properties: bool = False)[source]

Bases: object

A wrapper around CifFile to write CIF files from pymatgen Structure.

Parameters:

  • struct (Structure) – structure to write.

  • symprec (float) – If not none, finds the symmetry of the structure and writes the CIF with symmetry information. Passes symprec to the SpacegroupAnalyzer. See also refine_struct.

  • write_magmoms (bool) – If True, will write magCIF file. Incompatible with symprec

  • significant_figures (int) – Specifies precision for formatting of floats. Defaults to 8.

  • angle_tolerance (float) – Angle tolerance for symmetry finding. Passes angle_tolerance to the SpacegroupAnalyzer. Used only if symprec is not None.

  • refine_struct – Used only if symprec is not None. If True, get_refined_structure is invoked to convert input structure from primitive to conventional.

  • write_site_properties (bool) – Whether to write the Structure.site_properties to the CIF as _atom_site_{property name}. Defaults to False.

property cif_file: CifFile[source]

CifFile associated with the CifWriter.

write_file(filename: PathLike, mode: Literal['wt', 'at'] = 'wt') → None[source]

Write the CIF file.

str2float(text: str) → float[source]

Remove uncertainty brackets from strings and return the float.

pymatgen.io.common module

Module for defining common data used and produced by atomistic simulation packages.

class PMGDir(dirname: str | Path)[source]

Bases: Mapping

User-friendly class to access all files in a directory as pymatgen objects in a dict. For now, only VASP files are implemented but there is no reason why this cannot be extended to other types of files. Note that the files are lazily parsed to minimize initialization costs since not all files will be needed by all users.

Example:

` d = PMGDir(".") print(d["INCAR"]["NELM"]) print(d["vasprun.xml"].parameters) `

Parameters:

dirname – The directory containing the VASP calculation as a string or Path.

FILE_MAPPINGS: ClassVar = {'CHGCAR': 'pymatgen.io.vasp.Chgcar', 'CONTCAR': 'pymatgen.io.vasp.Poscar', 'DYNMAT': 'pymatgen.io.vasp.Dynmat', 'EIGENVAL': 'pymatgen.io.vasp.Eigenval', 'ELFCAR': 'pymatgen.io.vasp.Elfcar', 'IBZKPT': 'pymatgen.io.vasp.Kpoints', 'INCAR': 'pymatgen.io.vasp.Incar', 'KPOINTS': 'pymatgen.io.vasp.Kpoints', 'LOCPOT': 'pymatgen.io.vasp.Locpot', 'OSZICAR': 'pymatgen.io.vasp.Oszicar', 'OUTCAR': 'pymatgen.io.vasp.Outcar', 'POSCAR': 'pymatgen.io.vasp.Poscar', 'POTCAR': 'pymatgen.io.vasp.Potcar', 'PROCAR': 'pymatgen.io.vasp.Procar', 'WAVECAR': 'pymatgen.io.vasp.Wavecar', 'WAVEDER': 'pymatgen.io.vasp.Waveder', 'WSWQ': 'pymatgen.io.vasp.WSWQ', 'XDATCAR': 'pymatgen.io.vasp.Xdatcar', 'vasprun': 'pymatgen.io.vasp.Vasprun'}[source]
get_files_by_name(name: str) → dict[str, Any][source]

Returns all files with a given name. E.g., if you want all the OUTCAR files, set name=”OUTCAR”.

Returns:

object from PMGDir[filename]}

Return type:

{filename

reset()[source]

Reset all loaded files and recheck the directory for files. Use this when the contents of the directory has changed.

class VolumetricData(structure: Structure | IStructure, data: dict[str, np.ndarray], distance_matrix: np.ndarray | None = None, data_aug: np.ndarray | None = None)[source]

Bases: MSONable

A representation of volumetric data commonly used in atomistic simulation outputs, such as LOCPOT/CHGCAR files from VASP or cube files from other codes.

structure[source]

The crystal structure associated with the volumetric data. Represents the lattice and atomic coordinates using the Structure class.

Type:

Structure

is_spin_polarized[source]

Indicates if the simulation is spin-polarized. True for spin-polarized data (contains both total and spin-difference densities), False otherwise.

Type:

bool

dim[source]

The dimensions of the 3D volumetric grid along each axis in the format (nx, ny, nz), where nx, ny, and nz represent the number of grid points in the x, y, and z directions, respectively.

Type:

tuple[int, int, int]

data[source]

A dictionary containing the volumetric data. Keys include: - “total”: A 3D NumPy array representing the total spin density. - “diff” (optional): A 3D NumPy array representing the spin-difference

density (spin up - spin down). Typically present in spin-polarized calculations.

Type:

dict[str, np.ndarray]

ngridpts[source]

The total number of grid points in the volumetric data, calculated as nx * ny * nz using the grid dimensions.

Type:

int

Typically, this constructor is not used directly and the static from_file constructor is used. This constructor is designed to allow summation and other operations between VolumetricData objects.

Parameters:

  • structure (Structure) – associated with the volumetric data

  • data (dict[str, NDArray]) – Actual volumetric data.

  • distance_matrix (NDArray) – A pre-computed distance matrix if available. Useful so pass distance_matrices between sums, short-circuiting an otherwise expensive operation.

  • data_aug (NDArray) – Any extra information associated with volumetric data (typically augmentation charges)

copy() → Self[source]

Make a copy of VolumetricData object.

classmethod from_cube(filename: str | Path) → Self[source]

Initialize the cube object and store the data as pymatgen objects.

Parameters:

filename (str) – of the cube to read

classmethod from_hdf5(filename: str, **kwargs) → Self[source]

Reads VolumetricData from HDF5 file.

Parameters:

filename – Filename

Returns:

VolumetricData

get_average_along_axis(ind)[source]

Get the averaged total of the volumetric data a certain axis direction. For example, useful for visualizing Hartree Potentials from a LOCPOT file.

Parameters:

ind (int) – Index of axis.

Returns:

Average total along axis

get_axis_grid(ind)[source]

Get the grid for a particular axis.

Parameters:

ind (int) – Axis index.

get_integrated_diff(ind, radius, nbins=1)[source]

Get integrated difference of atom index ind up to radius. This can be an extremely computationally intensive process, depending on how many grid points are in the VolumetricData.

Parameters:

  • ind (int) – Index of atom.

  • radius (float) – Radius of integration.

  • nbins (int) – Number of bins. Defaults to 1. This allows one to obtain the charge integration up to a list of the cumulative charge integration values for radii for [radius/nbins, 2 * radius/nbins, ….].

Returns:

Differential integrated charge as a np array of [[radius, value], …]. Format is for ease of plotting. e.g. plt.plot(data[:,0], data[:,1])

linear_add(other, scale_factor=1.0)[source]

Method to do a linear sum of volumetric objects. Used by + and - operators as well. Returns a VolumetricData object containing the linear sum.

Parameters:

  • other (VolumetricData) – Another VolumetricData object

  • scale_factor (float) – Factor to scale the other data by.

Returns:

VolumetricData corresponding to self + scale_factor * other.

linear_slice(p1, p2, n=100)[source]

Get a linear slice of the volumetric data with n data points from point p1 to point p2, in the form of a list.

Parameters:

  • p1 (list) – 3-element list containing fractional coordinates of the first point.

  • p2 (list) – 3-element list containing fractional coordinates of the second point.

  • n (int) – Number of data points to collect, defaults to 100.

Returns:

List of n data points (mostly interpolated) representing a linear slice of the data from point p1 to point p2.

scale(factor)[source]

Scale the data in place by a factor.

property spin_data[source]

data}. Essentially, this provides the actual Spin.up and Spin.down data instead of the total and diff. Note that by definition, a non-spin-polarized run would have Spin.up data == Spin.down data.

Type:

The data decomposed into actual spin data as {spin

to_cube(filename, comment: str = '')[source]

Write the total volumetric data to a cube file format, which consists of two comment lines, a header section defining the structure IN BOHR, and the data.

Parameters:

  • filename (str) – Name of the cube file to be written.

  • comment (str) – If provided, this will be added to the second comment line

to_hdf5(filename)[source]

Write the VolumetricData to a HDF5 format, which is a highly optimized format for reading storing large data. The mapping of the VolumetricData to this file format is as follows:

VolumetricData.data -> f[“vdata”] VolumetricData.structure ->

f[“Z”]: Sequence of atomic numbers f[“fcoords”]: Fractional coords f[“lattice”]: Lattice in the pymatgen.core.Lattice matrix

format

f.attrs[“structure_json”]: String of JSON representation

Parameters:

filename (str) – Filename to output to.

value_at(x, y, z)[source]

Get a data value from self.data at a given point (x, y, z) in terms of fractional lattice parameters. Will be interpolated using a RegularGridInterpolator on self.data if (x, y, z) is not in the original set of data points.

Parameters:

  • x (float) – Fraction of lattice vector a.

  • y (float) – Fraction of lattice vector b.

  • z (float) – Fraction of lattice vector c.

Returns:

Value from self.data (potentially interpolated) corresponding to the point (x, y, z).

pymatgen.io.core module

This module defines the abstract interface for reading and writing calculation inputs in pymatgen. The interface comprises a 3-tiered hierarchy of classes.

  1. An InputFile object represents the contents of a single input file, e.g. the INCAR. This class standardizes file read and write operations.

  2. An InputSet is a dict-like container that maps filenames (keys) to file contents (either strings or InputFile objects). This class provides a standard write_input() method.

  3. InputGenerator classes implement a get_input_set method that, when provided with a structure, return an InputSet object with all parameters set correctly. Calculation input files can be written to disk with the write_inputs method.

If you want to implement a new InputGenerator, please take note of the following:

  1. You must implement a get_input_set method that returns an InputSet

  2. All customization of calculation parameters should be done in the __init__ method of the InputGenerator. The idea is that the generator contains the “recipe”, but nothing that is specific to a particular system. get_input_set takes system-specific information (such as structure) and applies the recipe.

  3. All InputGenerator must save all supplied args and kwargs as instance variables. e.g. self.my_arg = my_arg and self.kwargs = kwargs in the __init__. This ensures the as_dict and from_dict work correctly.

class InputFile[source]

Bases: MSONable

Abstract base class to represent a single input file. Note that use of this class is optional; it is possible create an InputSet that does not rely on underlying InputFile objects.

All InputFile classes must implement a get_str method, which is called by write_file.

If InputFile classes implement an __init__ method, they must assign all arguments to __init__ as attributes.

classmethod from_file(path: PathLike) → None[source]

Creates an InputFile object from a file.

Parameters:

path – Filename to read, including path.

Returns:

InputFile

abstractmethod classmethod from_str(contents: str) → None[source]

Create an InputFile object from a string.

Parameters:

contents – The contents of the file as a single string

Returns:

InputFile

abstractmethod get_str() → str[source]

Return a string representation of an entire input file.

write_file(filename: PathLike) → None[source]

Write the input file.

Parameters:

filename – The filename to output to, including path.

class InputGenerator[source]

Bases: MSONable

InputGenerator classes serve as generators for Input objects. They contain settings or sets of instructions for how to create Input from a set of coordinates or a previous calculation directory.

abstractmethod get_input_set(*args, **kwargs)[source]

Generate an InputSet object. Typically the first argument to this method will be a Structure or other form of atomic coordinates.

class InputSet(inputs: dict[PathLike, str | InputFile] | None = None, **kwargs)[source]

Bases: MSONable, MutableMapping

Abstract base class for all InputSet classes. InputSet are dict-like containers for all calculation input data.

Since InputSet inherits dict, it can be instantiated in the same manner, or a custom __init__ can be provided. Either way, self should be populated with keys that are filenames to be written, and values that are InputFile objects or strings representing the entire contents of the file.

All InputSet must implement from_directory. Implementing the validate method is optional.

Instantiate an InputSet.

Parameters:

  • inputs – The core mapping of filename: file contents that defines the InputSet data. This should be a dict where keys are filenames and values are InputFile objects or strings representing the entire contents of the file. If a value is not an InputFile object nor a str, but has a __str__ method, this str representation of the object will be written to the corresponding file. This mapping will become the .inputs attribute of the InputSet.

  • **kwargs – Any kwargs passed will be set as class attributes e.g. InputSet(inputs={}, foo=’bar’) will make InputSet.foo == ‘bar’.

classmethod from_directory(directory: PathLike) → None[source]

Construct an InputSet from a directory of one or more files.

Parameters:

directory – Directory to read input files from

validate() → bool[source]

A place to implement basic checks to verify the validity of an input set. Can be as simple or as complex as desired.

Will raise a NotImplementedError unless overloaded by the inheriting class.

write_input(directory: PathLike, make_dir: bool = True, overwrite: bool = True, zip_inputs: bool = False) → None[source]

Write inputs to one or more files.

Parameters:

  • directory – Directory to write input files to

  • make_dir – Whether to create the directory if it does not already exist.

  • overwrite – Whether to overwrite an input file if it already exists.

  • generate_inputs (Additional kwargs are passed to)

  • zip_inputs – If True, inputs will be zipped into a file with the same name as the InputSet (e.g., InputSet.zip)

exception ParseError[source]

Bases: SyntaxError

Indicate a problem was encountered during parsing due to unexpected formatting.

pymatgen.io.cssr module

This module provides input and output from the CSSR file format.

class Cssr(structure: Structure | IStructure)[source]

Bases: object

Basic object for working with Cssr file. Right now, only conversion from a Structure to a Cssr file is supported.

Parameters:

structure (Structure | IStructure) – A structure to create the Cssr object.

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

Reads a CSSR file to a Cssr object.

Parameters:

filename (str) – Filename to read from.

Returns:

Cssr object.

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

Reads a string representation to a Cssr object.

Parameters:

string (str) – A string representation of a CSSR.

Returns:

Cssr object.

write_file(filename)[source]

Write out a CSSR file.

Parameters:

filename (str) – Filename to write to.

pymatgen.io.fiesta module

This module implements input and output for Fiesta (http://perso.neel.cnrs.fr/xavier.blase/fiesta/index.html).

  • Nwchem2Fiesta: create the input files needed for a Fiesta run

  • FiestaRun: run gw_fiesta and bse_fiesta

  • Localized BasisSetReader

class BSEOutput(filename)[source]

Bases: object

A bse output file parser. The start…

All energies are in eV.

Parameters:

filename – Filename to read.

class BasisSetReader(filename)[source]

Bases: object

A basis set reader. Basis set are stored in data as a dict: :key l_zeta_ng for each nl orbitals which contain list of tuple (alpha, coef) for each of the ng gaussians in l_zeta orbital.

Parameters:

filename – Filename to read.

infos_on_basis_set()[source]
set_n_nlmo()[source]

The number of nlm orbitals for the basis set.

class FiestaInput(mol, correlation_grid: dict[str, str] | None = None, exc_dft_option: dict[str, str] | None = None, cohsex_options: dict[str, str] | None = None, gw_options: dict[str, str] | None = None, bse_tddft_options: dict[str, str] | None = None)[source]

Bases: MSONable

Input File for Fiesta called “cell.in” by default (mandatory in Fiesta for now).

Parameters:

  • mol – pymatgen mol

  • correlation_grid – dict

  • Exc_DFT_option – dict

  • COHSEX_options – dict

  • GW_options – dict

  • BSE_TDDFT_options – dict.

as_dict()[source]

MSONable dict.

dump_bse_data_in_gw_run(BSE_dump=True)[source]

Set the “do_bse” variable to 1 or 0 in cell.in.

Parameters:

BSE_dump (bool) – Defaults to True.

dump_tddft_data_in_gw_run(tddft_dump: bool = True)[source]

Set the do_tddft variable to 1 or 0 in cell.in.

Parameters:

tddft_dump (bool) – Defaults to True.

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

dct (dict) – Dict representation.

Returns:

FiestaInput

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

Read an Fiesta input from a file. Currently tested to work with files generated from this class itself.

Parameters:

filename – Filename to parse.

Returns:

FiestaInput object

classmethod from_str(string_input: str) → Self[source]

Read an FiestaInput from a string. Currently tested to work with files generated from this class itself.

Parameters:

string_input – string_input to parse.

Returns:

FiestaInput object

property infos_on_system[source]

Infos on initial parameters as in the log file of Fiesta.

static make_full_bse_densities_folder(folder)[source]

Mkdir “FULL_BSE_Densities” folder (needed for bse run) in the desired folder.

property molecule[source]

Molecule associated with this FiestaInput.

set_auxiliary_basis_set(folder, auxiliary_folder, auxiliary_basis_set_type='aug_cc_pvtz')[source]

copy in the desired folder the needed auxiliary basis set “X2.ion” where X is a specie.

Parameters:

  • auxiliary_folder – folder where the auxiliary basis sets are stored

  • auxiliary_basis_set_type – type of basis set (string to be found in the extension of the file name; must be in lower case). ex: C2.ion_aug_cc_pvtz_RI_Weigend find “aug_cc_pvtz”.

set_bse_options(n_excitations=10, nit_bse=200)[source]

Set parameters in cell.in for a BSE computation.

Parameters:

  • nv_bse – number of valence bands

  • nc_bse – number of conduction bands

  • n_excitations – number of excitations

  • nit_bse – number of iterations.

set_gw_options(nv_band=10, nc_band=10, n_iteration=5, n_grid=6, dE_grid=0.5)[source]

Set parameters in cell.in for a GW computation.

Parameters:

  • nv__band – number of valence bands to correct with GW

  • nc_band – number of conduction bands to correct with GW

  • n_iteration – number of iteration

  • dE_grid (n_grid and) – number of points and spacing in eV for correlation grid.

write_file(filename: str | Path) → None[source]

Write FiestaInput to a file.

Parameters:

filename – Filename.

class FiestaOutput(filename)[source]

Bases: object

A Fiesta output file parser.

All energies are in eV.

Parameters:

filename – Filename to read.

class FiestaRun(folder: str | None = None, grid: tuple[int, int, int] = (2, 2, 2), log_file: str = 'log')[source]

Bases: MSONable

To run FIESTA inside python:

if grid is [x,x] then bse runs if grid is [x,x,y] the fiesta(gw) runs otherwise it breaks.

Parameters:

  • folder – Folder to look for runs.

  • grid

  • log_file – logfile of Fiesta.

as_dict()[source]

MSONable dict.

bse_run()[source]

Perform BSE run.

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

dct (dict) – Dict representation.

Returns:

FiestaRun

run()[source]

Perform FIESTA (gw) run.

class Nwchem2Fiesta(folder, filename='nwchem', log_file='log_n2f')[source]

Bases: MSONable

To run NWCHEM2FIESTA inside python:

If nwchem.nw is the input, nwchem.out the output, and structure.movecs the “movecs” file, the syntax to run NWCHEM2FIESTA is: NWCHEM2FIESTA nwchem.nw nwchem.nwout structure.movecs > log_n2f

Parameters:

  • folder – where are stored the nwchem

  • filename – name of nwchem files read by NWCHEM2FIESTA (filename.nw, filename.nwout and filename.movecs)

  • logfile – logfile of NWCHEM2FIESTA.

as_dict()[source]

MSONable dict.

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

dct (dict) – Dict representation.

Returns:

Nwchem2Fiesta

run()[source]

Perform actual NWCHEM2FIESTA run.

pymatgen.io.gaussian module

This module implements input and output processing from Gaussian.

class GaussianInput(mol, charge=None, spin_multiplicity=None, title=None, functional='HF', basis_set='6-31G(d)', route_parameters=None, input_parameters=None, link0_parameters=None, dieze_tag='#P', gen_basis=None)[source]

Bases: object

A Gaussian input file.

Parameters:

  • mol – Input molecule. It can either be a Molecule object, a string giving the geometry in a format supported by Gaussian, or None. If the molecule is None, you will need to use read it in from a checkpoint. Consider adding CHK to the link0_parameters.

  • charge – Charge of the molecule. If None, charge on molecule is used. Defaults to None. This allows the input file to be set a charge independently from the molecule itself. If mol is not a Molecule object, then you must specify a charge.

  • spin_multiplicity –

    Spin multiplicity of molecule. Defaults to None, which means that the spin multiplicity is set to 1 if the molecule has no unpaired electrons and to 2 if there are unpaired electrons. If mol is not a Molecule object, then you

    must specify the multiplicity

  • title – Title for run. Defaults to formula of molecule if None.

  • functional – Functional for run.

  • basis_set – Basis set for run.

  • route_parameters – Additional route parameters as a dict. For example, {‘SP’:””, “SCF”:”Tight”}

  • input_parameters – Additional input parameters for run as a dict. Used for example, in PCM calculations. e.g. {“EPS”:12}

  • link0_parameters – Link0 parameters as a dict. e.g. {“%mem”: “1000MW”}

  • dieze_tag – # preceding the route line. E.g. “#p”

  • gen_basis – allows a user-specified basis set to be used in a Gaussian calculation. If this is not None, the attribute basis_set will be set to “Gen”.

as_dict()[source]

MSONable dict.

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

dct – dict.

Returns:

GaussianInput

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

Creates GaussianInput from a file.

Parameters:

filename – Gaussian input filename

Returns:

GaussianInput object

classmethod from_str(contents: str) → Self[source]

Creates GaussianInput from a string.

Parameters:

contents – String representing an Gaussian input file.

Returns:

GaussianInput object

get_cart_coords() → str[source]

Return the Cartesian coordinates of the molecule.

get_zmatrix()[source]

Get a z-matrix representation of the molecule.

property molecule[source]

Molecule associated with this GaussianInput.

to_str(cart_coords=False)[source]

Return GaussianInput string.

Parameters:

cart_coords (bool) – If True, return Cartesian coordinates instead of z-matrix. Defaults to False.

write_file(filename, cart_coords=False)[source]

Write the input string into a file.

Option: see __str__ method

class GaussianOutput(filename: PathLike)[source]

Bases: object

Parser for Gaussian output files.

Note: Still in early beta.

structures[source]

All structures from the calculation in the standard orientation. If the symmetry is not considered, the standard orientation is not printed out and the input orientation is used instead. Check the standard_orientation attribute.

Type:

list[Structure]

structures_input_orientation[source]

All structures from the calculation in the input orientation or the Z-matrix orientation (if an opt=z-matrix was requested).

Type:

list

opt_structures[source]

All optimized structures from the calculation in the standard orientation, if the attribute ‘standard_orientation’ is True, otherwise in the input or the Z-matrix orientation.

Type:

list

energies[source]

All energies from the calculation.

Type:

list

eigenvalues[source]

List of eigenvalues for the last geometry.

Type:

list

MO_coefficients[source]

Matrix of MO coefficients for the last geometry.

Type:

list

cart_forces[source]

All Cartesian forces from the calculation.

Type:

list

frequencies[source]

A list for each freq calculation and for each mode of a dict with {

“frequency”: freq in cm-1, “symmetry”: symmetry tag “r_mass”: Reduce mass, “f_constant”: force constant, “IR_intensity”: IR Intensity, “mode”: normal mode

}

The normal mode is a 1D vector of dx, dy dz of each atom.

Type:

list

hessian[source]

Matrix of second derivatives of the energy with respect to cartesian coordinates in the input orientation frame. Need #P in the route section in order to be in the output.

Type:

ndarray

properly_terminated[source]

True if run has properly terminated.

Type:

bool

is_pcm[source]

True if run is a PCM run.

Type:

bool

is_spin[source]

True if it is an unrestricted run.

Type:

bool

stationary_type[source]

If it is a relaxation run, indicates whether it is a minimum (Minimum) or a saddle point (“Saddle”).

Type:

str

corrections[source]

Thermochemical corrections if this run is a Freq run as a dict. Keys are “Zero-point”, “Thermal”, “Enthalpy” and “Gibbs Free Energy”.

Type:

dict

functional[source]

Functional used in the run.

Type:

str

basis_set[source]

Basis set used in the run.

Type:

str

route[source]

Additional route parameters as a dict. For example, {‘SP’:””, “SCF”:”Tight”}.

Type:

dict

dieze_tag[source]

# preceding the route line, e.g. “#P”.

Type:

str

link0[source]

Link0 parameters as a dict. e.g. {“%mem”: “1000MW”}.

Type:

dict

charge[source]

Charge for structure.

Type:

int

spin_multiplicity[source]

Spin multiplicity for structure.

Type:

int

num_basis_func[source]

Number of basis functions in the run.

Type:

int

electrons[source]

Number of alpha and beta electrons as (N alpha, N beta).

Type:

tuple

pcm[source]

PCM parameters and output if available.

Type:

dict

errors[source]

Error if not properly terminated (list to be completed in error_defs).

Type:

list

Mulliken_charges[source]

Mulliken atomic charges.

Type:

list

eigenvectors[source]

Matrix of shape (num_basis_func, num_basis_func). Each column is an eigenvectors and contains AO coefficients of an MO. eigenvectors[Spin] = mat(num_basis_func, num_basis_func).

Type:

dict

molecular_orbital[source]

MO development coefficients on AO in a more convenient array dict for each atom and basis set label. mo[Spin][OM j][atom i] = {AO_k: coeff, AO_k: coeff … }.

Type:

dict

atom_basis_labels[source]

Labels of AO for each atoms. These labels are those used in the output of molecular orbital coefficients (POP=Full) and in the molecular_orbital array dict. atom_basis_labels[iatom] = [AO_k, AO_k, …].

Type:

list

resumes[source]

List of gaussian data resume given at the end of the output file before the quotation. The resumes are given as string.

Type:

list

title[source]

Title of the gaussian run.

Type:

str

standard_orientation[source]

If True, the geometries stored in the structures are in the standard orientation. Else, the geometries are in the input orientation.

Type:

bool

bond_orders[source]

Dict of bond order values read in the output file such as: {(0, 1): 0.8709, (1, 6): 1.234, …}. The keys are the atom indexes and the values are the Wiberg bond indexes that are printed using pop=NBOREAD and $nbo bndidx $end.

Type:

dict

to_input()[source]

Return a GaussianInput object using the last geometry and the same calculation parameters.

read_scan()[source]

Read a potential energy surface from a gaussian scan calculation.

get_scan_plot()[source]

Get a matplotlib plot of the potential energy surface

save_scan_plot()[source]

Save a matplotlib plot of the potential energy surface to a file

Parameters:

filename – Filename of Gaussian output file.

as_dict()[source]

JSON-serializable dict representation.

property final_energy[source]

Final energy in Gaussian output.

property final_structure[source]

Final structure in Gaussian output.

get_scan_plot(coords=None)[source]

Get a matplotlib plot of the potential energy surface.

Parameters:

coords – internal coordinate name to use as abscissa.

get_spectre_plot(sigma=0.05, step=0.01)[source]

Get a matplotlib plot of the UV-visible xas. Transitions are plotted as vertical lines and as a sum of normal functions with sigma with. The broadening is applied in energy and the xas is plotted as a function of the wavelength.

Parameters:

  • sigma – Full width at half maximum in eV for normal functions.

  • step – bin interval in eV

Returns:

{“energies”: values, “lambda”: values, “xas”: values}

where values are lists of abscissa (energies, lambda) and the sum of gaussian functions (xas).

A matplotlib plot.

Return type:

A dict

read_excitation_energies()[source]

Read a excitation energies after a TD-DFT calculation.

Returns:

A list of tuple for each transition such as

[(energie (eV), lambda (nm), oscillatory strength), … ]

Return type:

A list

read_scan()[source]

Read a potential energy surface from a gaussian scan calculation.

Returns:

{“energies”: […], “coords”: {“d1”: […], “A2”, […], … }} “energies” are the energies of all points of the potential energy surface. “coords” are the internal coordinates used to compute the potential energy surface and the internal coordinates optimized, labelled by their name as defined in the calculation.

Return type:

dict[str, list]

save_scan_plot(filename='scan.pdf', img_format='pdf', coords=None)[source]

Save matplotlib plot of the potential energy surface to a file.

Parameters:

  • filename – Filename to write to.

  • img_format – Image format to use. Defaults to EPS.

  • coords – internal coordinate name to use as abcissa.

save_spectre_plot(filename='spectre.pdf', img_format='pdf', sigma=0.05, step=0.01)[source]

Save matplotlib plot of the spectre to a file.

Parameters:

  • filename – Filename to write to.

  • img_format – Image format to use. Defaults to EPS.

  • sigma – Full width at half maximum in eV for normal functions.

  • step – bin interval in eV

to_input(mol=None, charge=None, spin_multiplicity=None, title=None, functional=None, basis_set=None, route_parameters=None, input_parameters=None, link0_parameters=None, dieze_tag=None, cart_coords=False)[source]

Create a new input object using by default the last geometry read in the output file and with the same calculation parameters. Arguments are the same as GaussianInput class.

Returns:

the gaussian input object

Return type:

GaussianInput

read_route_line(route)[source]

read route line in gaussian input/output and return functional basis_set and a dictionary of other route parameters.

Parameters:

route (str) – the route line

Returns:

the method (HF, PBE …) basis_set (str) : the basis set route (dict) : dictionary of parameters

Return type:

functional (str)

pymatgen.io.icet module

class IcetSQS(structure: Structure | IStructure, scaling: int, instances: int | None, cluster_cutoffs: dict[int, float], sqs_method: str | None = None, sqs_kwargs: dict | None = None)[source]

Bases: object

Interface to the Icet library of SQS structure generation tools.

https://icet.materialsmodeling.org

Instantiate an IcetSQS interface.

Parameters:

  • structure (Structure) – disordered structure to compute SQS

  • scaling (int) – SQS supercell contains scaling * len(structure) sites

  • instances (int) – number of parallel SQS jobs to run

  • cluster_cutoffs (dict) – dict of cluster size (pairs, triplets, …) and the size of the cluster

Kwargs:
sqs_method (str or None): if a str, one of (“enumeration”, “monte_carlo”)

If None, default to “enumeration” for a supercell of < 24 sites, and “monte carlo” otherwise.

sqs_kwargs (dict): kwargs to pass to the icet SQS generators.

See self.sqs_kwarg_names for possible options.

enumerate_sqs_structures(cluster_space: _ClusterSpace | None = None) → list[source]

Generate an SQS by enumeration of all possible arrangements.

Adapted from icet.tools.structure_generation.generate_sqs_by_enumeration to accommodate multiprocessing.

Parameters:

cluster_space (ClusterSpace) – ClusterSpace of the SQS search.

Returns:

dicts of the form: {

“structure”: SQS structure, “objective_function”: SQS objective function,

}

Return type:

list

get_icet_sqs_obj(material: Atoms | Structure, cluster_space: _ClusterSpace | None = None) → float[source]

Get the SQS objective function.

Parameters:

  • material (pymatgen.Structure | ase.Atoms) – structure to compute SQS objective function for.

  • cluster_space (ClusterSpace) – ClusterSpace of the SQS search.

Returns:

the SQS objective function

Return type:

float

monte_carlo_sqs_structures() → list[source]

Run self.instances Monte Carlo SQS search with Icet.

run() → Sqs[source]

Run the SQS search with icet.

Returns:

pymatgen Sqs object

sqs_kwarg_names: ClassVar[dict[str, tuple[str, ...]]] = {'enumeration': ('include_smaller_cells', 'pbc', 'optimality_weight', 'tol'), 'monte_carlo': ('include_smaller_cells', 'pbc', 'T_start', 'T_stop', 'n_steps', 'optimality_weight', 'random_seed', 'tol')}[source]
sqs_methods: tuple[str, ...] = ('enumeration', 'monte_carlo')[source]

pymatgen.io.jarvis module

This module provides conversion between the JARVIS Atoms object and pymatgen Structure objects.

class JarvisAtomsAdaptor[source]

Bases: object

Adaptor serves as a bridge between JARVIS Atoms and pymatgen objects.

static get_atoms(structure)[source]

Get JARVIS Atoms object from pymatgen structure.

Parameters:

structure – pymatgen Structure

Returns:

JARVIS Atoms object

static get_structure(atoms)[source]

Get pymatgen structure from JARVIS Atoms.

Parameters:

atoms – JARVIS Atoms object

Returns:

Equivalent pymatgen Structure

pymatgen.io.lmto module

Module for implementing a CTRL file object class for the Stuttgart LMTO-ASA code. It will primarily be used to generate a pymatgen Structure object in the pymatgen.electronic_structure.cohp.py module.

class LMTOCopl(filename='COPL', to_eV=False)[source]

Bases: object

Read COPL files, which contain COHP data.

cohp_data[source]

Contains the COHP data of the form: {bond: {“COHP”: {Spin.up: cohps, Spin.down:cohps},

“ICOHP”: {Spin.up: icohps, Spin.down: icohps}, “length”: bond length}

Type:

dict

efermi[source]

The Fermi energy in Ry or eV.

Type:

float

energies[source]

Sequence of energies in Ry or eV.

Type:

list

is_spin_polarized[source]

True if the calculation is spin-polarized.

Type:

bool

Parameters:

  • filename – filename of the COPL file. Defaults to “COPL”.

  • to_eV – LMTO-ASA gives energies in Ry. To convert energies into eV, set to True. Defaults to False for energies in Ry.

class LMTOCtrl(structure: Structure | IStructure, header: str | None = None, version: str = 'LMASA-47')[source]

Bases: object

Parse CTRL files from the Stuttgart LMTO-ASA code. Currently, only HEADER, VERS and the structure can be used.

Parameters:

  • structure (Structure) – pymatgen object.

  • header (str) – The header for the CTRL file. Defaults to None.

  • version (str) – The LMTO version that is used for the VERS category. Defaults to version (4.7).

as_dict()[source]

Get the CTRL as a dictionary. “SITE” and “CLASS” are of the form {‘CATEGORY’: {‘TOKEN’: value}}, the rest is of the form ‘TOKEN’/’CATEGORY’: value. It gets the conventional standard structure because primitive cells use the conventional a-lattice parameter as the scaling factor and not the a-lattice parameter of the primitive cell.

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

Creates a CTRL file object from a dictionary. The dictionary must contain the items “ALAT”, PLAT” and “SITE”.

Valid dictionary items are:

ALAT: the a-lattice parameter PLAT: (3x3) array for the lattice vectors SITE: list of dictionaries: {‘ATOM’: class label, ‘POS’: (3x1) array of fractional coordinates} CLASS (optional): list of unique atom labels as str SPCGRP (optional): space group symbol (str) or number (int) HEADER (optional): HEADER text as a str VERS (optional): LMTO version as a str

Parameters:

dct – The CTRL file as a dictionary.

Returns:

An LMTOCtrl object.

classmethod from_file(filename: str | Path = 'CTRL', **kwargs) → Self[source]

Creates a CTRL file object from an existing file.

Parameters:

filename – The name of the CTRL file. Defaults to ‘CTRL’.

Returns:

An LMTOCtrl object.

classmethod from_str(data: str, sigfigs: int = 8) → Self[source]

Creates a CTRL file object from a string. This will mostly be used to read an LMTOCtrl object from a CTRL file. Empty spheres are ignored.

Parameters:

data (str) – String representation of the CTRL file.

Returns:

An LMTOCtrl object.

get_str(sigfigs=8) → str[source]

Generate the string representation of the CTRL file. This is the minimal CTRL file necessary to execute lmhart.run.

write_file(filename='CTRL', **kwargs)[source]

Write a CTRL file with structure, HEADER, and VERS that can be used as input for lmhart.run.

pymatgen.io.multiwfn module

This module implements input/output processing from Multiwfn.

Currently, the focus of this module is on processing Quantum Theory of Atoms in Molecules (QTAIM) outputs from Multiwfn. Additional features may be added over time as needed/desired.

add_atoms(molecule: Molecule, organized_cps: dict[str, dict[Any, dict[str, Any]]], bond_atom_criterion: Literal['qtaim', 'distance', 'combined'] = 'combined', dist_threshold_bond: float = 1.0, dist_threshold_ring_cage: float = 3.0, distance_margin: float = 0.5) → dict[str, dict[str, dict[str, Any]]][source]

Modify bond, ring, and cage CPs to include information about surrounding critical points. Bonds will include information about the atoms that make up the bond. Rings will include the names of neighboring bonds and the indices of the atoms involved, and cages will include information on neighboring rings, bonds, and the atoms involved.

Parameters:

  • molecule (Molecule) – structure corresponding to this Multiwfn calculation

  • organized_cps (Dict[str, Dict[Any, Dict[str, Any]]]) – Keys are CP categories (“atom”, “bond”, “ring”, and “cage”). Values are themselves dictionaries, where the keys are CP names (or atom indices) and the values are CP descriptors

  • bond_atom_criterion (Literal["qtaim", "distance", "combined"]) – If this is “qtaim”, the inherent bonding definition obtained from QTAIM/Multiwfn will be used to link bond CPs to atoms involved in those bonds. If it is “distance”, a distance-based metric will be used instead, where the atoms closest to the bond CP will be assumed to be bonded. If this is “combined”, then the QTAIM/Multiwfn definition will be used where available, and a distance metric will be used for all bond CPs lacking a definition from QTAIM/Multiwfn. NOTE: to use “qtaim” or “combined” as bond_atom_criterion, you must have used map_atoms_cps to link atom numbers from Multiwfn to atom indices in molecule.

  • dist_threshold_bond (float) – If the nearest atoms to a bond CP are further from the bond CP than this threshold (default 1.0 Angstrom), then a warning will be raised.

  • dist_threshold_ring_cage (float) – If the nearest bond CPs to a ring CP or the nearest ring CPs to a cage CP are further than this threshold (default 3.0 Angstrom), then a warning will be raised.

  • distance_margin (float) – Rings must be made up of at least three bonds, and cages must be made up of at least three rings. We therefore define rings by the three closest bond CPs and cages by the three closest ring CPs. We associate additional bond/ring CPs with ring/cage CPs if they are no further than the third-closest bond/ring CP, plus this margin. Default is 0.5 Angstrom

Returns:

CP dict with additional information added.

Return type:

modified_organized_cps (Dict[str, Dict[str, Dict[str, Any]]])

extract_info_from_cp_text(lines_split: list[list[str]], cp_type: Literal['atom', 'bond', 'ring', 'cage'], conditionals: dict[str, list[str]]) → tuple[str, dict[str, Any]][source]

Extract specific information from a Multiwfn QTAIM output.

Parameters:

  • lines_split (List[List[str]]) – List of lines from a (pre-processed) CP file, containing only information regarding one critical point, split by whitespace

  • cp_type – Type of critical point. Currently, can be “atom”, “bond”, “ring”, or “cage”

  • conditionals (Dict[str, List[str]]) – Parameters to extract with strings to search for to see if the data is present

Returns:

dictionary of critical point information

Return type:

cp_dict

get_qtaim_descs(file: PathLike) → dict[str, dict[str, Any]][source]

Parse CPprop file from multiwfn by parsing each individual critical-point section.

Parameters:

file (PathLike) – path to CPprop file

Returns:

Output dictionary of QTAIM descriptors

Return type:

descriptors (Dict[str, Dict[str, Any]])

map_atoms_cps(molecule: Molecule, atom_cp_dict: dict[str, dict[str, Any]], max_distance: float = 0.5) → tuple[dict[int, dict[str, Any]], list[int]][source]

Connect atom CPs to atoms by their positions.

Parameters:

  • molecule (Molecule) – structure corresponding to this Multiwfn calculation

  • atom_cp_dict (Dict[str, Dict[str, Any]]) – Dictionary where keys are critical point names and values are descriptors, including element symbol and position

  • max_distance (float) – Maximum distance (in Angstrom) that a critical point can be away from an atom center and be associated with that atom. Default is 0.5 Angstrom

Returns:

Dictionary mapping atomic indices to atom critical point

descriptors

missing_atoms (List[int]): list of dft atoms that do not have a cp found in qtaim

Return type:

index_to_cp_desc (Dict[int, Dict[str, Any]])

match_atom_cp(molecule: Molecule, index: int, atom_cp_dict: dict[str, dict[str, Any]], max_distance: float = 0.5) → tuple[str | None, dict][source]

From a dictionary with an atom’s position and element symbol, find the corresponding cp in the atom CP dictionary

Parameters:

  • molecule (Molecule) – structure corresponding to this Multiwfn calculation

  • index (int) – index of the atom to be matched

  • atom_cp_dict (Dict[str, Dict[str, Any]]) – Dictionary where keys are critical point names and values are descriptors, including element symbol and position

  • max_distance (float) – Maximum distance (in Angstrom) that a critical point can be away from an atom center and be associated with that atom. Default is 0.5 Angstrom

Returns:

Key of atom_cp_dict; the name of the atom critical point corresponding to this atom. If

no match is found, this will be None

cp_dict (Dict): Dictionary of CP descriptors matching this atom

Return type:

cp_name (str | None)

parse_cp(lines: list[str]) → tuple[str | None, dict[str, Any]][source]

Parse information from a single QTAIM critical point.

Parameters:

lines (List[str]) – list of lines from a (preparsed) CP file, containing only information regarding one critical point

Returns:

dictionary of critical point information

Return type:

cp_dict

process_multiwfn_qtaim(molecule: Molecule, file: PathLike, bond_atom_criterion: Literal['qtaim', 'distance'] = 'distance', max_distance_atom: float = 0.5, dist_threshold_bond: float = 1.0, dist_threshold_ring_cage: float = 3.0, distance_margin: float = 0.5) → dict[str, dict[Any, dict[str, Any]]][source]

Process quantum theory of atoms in molecules (QTAIM) outputs from Multiwfn.

Parameters:

  • molecule (Molecule) – structure corresponding to this Multiwfn calculation

  • file (PathLike) – path to CPprop file containing QTAIM information

  • bond_atom_criterion (Literal["qtaim", "distance"]) – If “qtaim”, the inherent bonding definition obtained from QTAIM/Multiwfn will be used to link bond CPs to atoms involved in those bonds; if “distance”, a distance-based metric will be used instead, where the atoms closest to the bond CP will be assumed to be bonded.

  • max_distance (float) – Maximum distance (in Angstrom) that an atom critical point can be away from an atom center and be associated with that atom. Default is 0.5 Angstrom

  • dist_threshold_bond (float) – If the nearest atoms to a bond CP are further from the bond CP than this threshold (default 1.0 Angstrom), then a warning will be raised.

  • dist_threshold_ring_cage (float) – If the nearest bond CPs to a ring CP or the nearest ring CPs to a cage CP are further than this threshold (default 3.0 Angstrom), then a warning will be raised.

  • distance_margin (float) – Rings must be made up of at least three bonds, and cages must be made up of at least three rings. We therefore define rings by the three closest bond CPs and cages by the three closest ring CPs. We associate additional bond/ring CPs with ring/cage CPs if they are no further than the third-closest bond/ring CP, plus this margin. Default is 0.5 Angstrom

Returns:

QTAIM descriptors, organized by type (“atom”, “bond”,

”ring”, “cage”), with additional metadata added to bond, ring, and cage CPs

Return type:

with_atoms (Dict[str, Dict[str, Dict[str, Any]]])

separate_cps_by_type(qtaim_descs: dict[Any, dict[str, Any]]) → dict[str, dict[Any, dict[str, Any]]][source]

Separates QTAIM descriptors by type (atom, bond, ring, or cage)

Parameters:

qtaim_descs (Dict[str, Dict[str, Any]]) – Dictionary where keys are CP names and values are dictionaries of descriptors obtained from get_qtaim_descs and parse_cp

Returns:

Dictionary of organized QTAIM critical points and their

descriptors. Keys are “atom”, “bond”, “ring”, and “cage”, and values are dicts {<CP name>: <QTAIM descriptors>}

Return type:

organized_descs (Dict[str, Dict[str, Dict[str, Any]]])

pymatgen.io.nwchem module

This module implements input and output processing from Nwchem.

2015/09/21 - Xin Chen (chenxin13@mails.tsinghua.edu.cn):

NwOutput will read new kinds of data:

  1. normal hessian matrix. [“hessian”]

  2. projected hessian matrix. [“projected_hessian”]

  3. normal frequencies. [“normal_frequencies”]

For backward compatibility, the key for accessing the projected frequencies is still ‘frequencies’.

2015/10/12 - Xin Chen

NwOutput will read new kinds of data:

  1. forces. [“forces”]

class NwInput(mol, tasks, directives=None, geometry_options=('units', 'angstroms'), symmetry_options=None, memory_options=None)[source]

Bases: MSONable

An object representing a Nwchem input file, which is essentially a list of tasks on a particular molecule.

Parameters:

  • mol – Input molecule. If molecule is a single string, it is used as a direct input to the geometry section of the Gaussian input file.

  • tasks – List of NwTasks.

  • directives – List of root level directives as tuple. e.g. [(“start”, “water”), (“print”, “high”)]

  • geometry_options – Additional list of options to be supplied to the geometry. e.g. [“units”, “angstroms”, “noautoz”]. Defaults to (“units”, “angstroms”).

  • symmetry_options – Addition list of option to be supplied to the symmetry. E.g. [“c1”] to turn off the symmetry

  • memory_options – Memory controlling options. str. E.g “total 1000 mb stack 400 mb”.

as_dict()[source]

Get MSONable dict.

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

dct (dict) – Dict representation.

Returns:

NwInput

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

Read an NwInput from a file. Currently tested to work with files generated from this class itself.

Parameters:

filename – Filename to parse.

Returns:

NwInput object

classmethod from_str(string_input: str) → Self[source]

Read an NwInput from a string. Currently tested to work with files generated from this class itself.

Parameters:

string_input – string_input to parse.

Returns:

NwInput object

property molecule[source]

Molecule associated with this GaussianInput.

write_file(filename)[source]
Parameters:

filename (str) – Filename.

exception NwInputError[source]

Bases: Exception

Error class for NwInput.

class NwOutput(filename)[source]

Bases: object

A Nwchem output file parser. Very basic for now - supports only dft and only parses energies and geometries. Please note that Nwchem typically outputs energies in either au or kJ/mol. All energies are converted to eV in the parser.

Parameters:

filename – Filename to read.

get_excitation_spectrum(width=0.1, npoints=2000)[source]

Generate an excitation spectra from the singlet roots of TDDFT calculations.

Parameters:

  • width (float) – Width for Gaussian smearing.

  • npoints (int) – Number of energy points. More points => smoother curve.

Returns:

can be plotted using pymatgen.vis.plotters.SpectrumPlotter.

Return type:

ExcitationSpectrum

parse_tddft()[source]

Parses TDDFT roots. Adapted from nw_spectrum.py script.

Returns:

A dict of the form {“singlet”: [dict, …], “triplet”: [dict, …]} where

each sub-dict is of the form {“energy”: float, “osc_strength”: float}.

Return type:

dict[str, list]

class NwTask(charge, spin_multiplicity, basis_set, basis_set_option='cartesian', title=None, theory='dft', operation='optimize', theory_directives=None, alternate_directives=None)[source]

Bases: MSONable

Base task for Nwchem.

Very flexible arguments to support many types of potential setups. Users should use more friendly static methods unless they need the flexibility.

Parameters:

  • charge – Charge of the molecule. If None, charge on molecule is used. Defaults to None. This allows the input file to be set a charge independently from the molecule itself.

  • spin_multiplicity – Spin multiplicity of molecule. Defaults to None, which means that the spin multiplicity is set to 1 if the molecule has no unpaired electrons and to 2 if there are unpaired electrons.

  • basis_set – The basis set used for the task as a dict. e.g. {“C”: “6-311++G**”, “H”: “6-31++G**”}.

  • basis_set_option – cartesian (default) | spherical,

  • title – Title for the task. Defaults to None, which means a title based on the theory and operation of the task is autogenerated.

  • theory – The theory used for the task. Defaults to “dft”.

  • operation – The operation for the task. Defaults to “optimize”.

  • theory_directives – A dict of theory directives. For example, if you are running dft calculations, you may specify the exchange correlation functional using {“xc”: “b3lyp”}.

  • alternate_directives – A dict of alternate directives. For example, to perform cosmo calculations and dielectric constant of 78, you’d supply {‘cosmo’: {“dielectric”: 78}}.

as_dict()[source]

Get MSONable dict.

classmethod dft_task(mol, xc='b3lyp', **kwargs)[source]

A class method for quickly creating DFT tasks with optional cosmo parameter .

Parameters:

  • mol – Input molecule

  • xc – Exchange correlation to use.

  • kwargs – Any of the other kwargs supported by NwTask. Note the theory is always “dft” for a dft task.

classmethod esp_task(mol, **kwargs)[source]

A class method for quickly creating ESP tasks with RESP charge fitting.

Parameters:

  • mol – Input molecule

  • kwargs – Any of the other kwargs supported by NwTask. Note the theory is always “dft” for a dft task.

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

dct (dict) – Dict representation.

Returns:

NwTask

classmethod from_molecule(mol, theory, charge=None, spin_multiplicity=None, basis_set='6-31g', basis_set_option='cartesian', title=None, operation='optimize', theory_directives=None, alternate_directives=None) → Self[source]

Very flexible arguments to support many types of potential setups. Users should use more friendly static methods unless they need the flexibility.

Parameters:

  • mol – Input molecule

  • charge – Charge of the molecule. If None, charge on molecule is used. Defaults to None. This allows the input file to be set a charge independently from the molecule itself.

  • spin_multiplicity – Spin multiplicity of molecule. Defaults to None, which means that the spin multiplicity is set to 1 if the molecule has no unpaired electrons and to 2 if there are unpaired electrons.

  • basis_set – The basis set to be used as string or a dict. e.g. {“C”: “6-311++G**”, “H”: “6-31++G**”} or “6-31G”. If string, same basis set is used for all elements.

  • basis_set_option – cartesian (default) | spherical,

  • title – Title for the task. Defaults to None, which means a title based on the theory and operation of the task is autogenerated.

  • theory – The theory used for the task. Defaults to “dft”.

  • operation – The operation for the task. Defaults to “optimize”.

  • theory_directives – A dict of theory directives. For example, if you are running dft calculations, you may specify the exchange correlation functional using {“xc”: “b3lyp”}.

  • alternate_directives – A dict of alternate directives. For example, to perform cosmo calculations with DFT, you’d supply {‘cosmo’: “cosmo”}.

operations: ClassVar[dict[str, str]] = {'': 'dummy', 'dynamics': 'Perform classical molecular dynamics.', 'energy': 'Evaluate the single point energy.', 'freq': 'Same as frequencies.', 'frequencies': 'Compute second derivatives and print out an analysis of molecular vibrations.', 'gradient': 'Evaluate the derivative of the energy with respect to nuclear coordinates.', 'hessian': 'Compute second derivatives.', 'optimize': 'Minimize the energy by varying the molecular structure.', 'property': 'Calculate the properties for the wave function.', 'saddle': 'Conduct a search for a transition state (or saddle point).', 'thermodynamics': 'Perform multi-configuration thermodynamic integration using classical MD.', 'vscf': 'Compute anharmonic contributions to the vibrational modes.'}[source]
theories: ClassVar[dict[str, str]] = {'band': 'Pseudopotential plane-wave DFT for solids using NWPW', 'ccsd': 'Coupled-cluster single and double excitations', 'ccsd(t)': 'Coupled-cluster linearized triples approximation', 'ccsd+t(ccsd)': 'Fourth order triples contribution', 'dft': 'DFT', 'direct_mp2': 'MP2 using a full-direct algorithm', 'esp': 'ESP', 'g3gn': 'some description', 'mcscf': 'Multiconfiguration SCF', 'md': 'Classical molecular dynamics simulation', 'mp2': 'MP2 using a semi-direct algorithm', 'pspw': 'Pseudopotential plane-wave DFT for molecules and insulating solids using NWPW', 'rimp2': 'MP2 using the RI approximation', 'scf': 'Hartree-Fock', 'selci': 'Selected CI with perturbation correction', 'sodft': 'Spin-Orbit DFT', 'tce': 'Tensor Contraction Engine', 'tddft': 'Time Dependent DFT'}[source]

pymatgen.io.openff module

Utility functions for classical MD subpackage.

add_conformer(openff_mol: tk.Molecule, geometry: Molecule | None) → tuple[tk.Molecule, dict[int, int]][source]

Add conformers to an OpenFF Molecule based on the provided geometry.

If a geometry is provided, infers an OpenFF Molecule from it, finds an atom mapping between the inferred molecule and the input molecule, and adds the conformer coordinates to the input molecule. If no geometry is provided, generates a single conformer.

Parameters:

  • openff_mol (tk.Molecule) – The OpenFF Molecule to add conformers to.

  • geometry (Union[pymatgen.core.Molecule, None]) – The geometry to use for adding conformers.

Returns:

A tuple containing the updated OpenFF

Molecule with added conformers and a dictionary representing the atom mapping.

Return type:

Tuple[tk.Molecule, Dict[int, int]]

assign_partial_charges(openff_mol: tk.Molecule, atom_map: dict[int, int], charge_method: str, partial_charges: None | list[float]) → tk.Molecule[source]

Assign partial charges to an OpenFF Molecule.

If partial charges are provided, assigns them to the molecule based on the atom mapping. If the molecule has only one atom, assigns the total charge as the partial charge. Otherwise, assigns partial charges using the specified charge method.

Parameters:

  • openff_mol (tk.Molecule) – The OpenFF Molecule to assign partial charges to.

  • atom_map (Dict[int, int]) – A dictionary representing the atom mapping.

  • charge_method (str) – The charge method to use if partial charges are not provided.

  • partial_charges (Union[None, List[float]]) – A list of partial charges to assign or None to use the charge method.

Returns:

The OpenFF Molecule with assigned partial charges.

Return type:

tk.Molecule

create_openff_mol(smile: str, geometry: Molecule | str | Path | None = None, charge_scaling: float = 1, partial_charges: list[float] | None = None, backup_charge_method: str = 'am1bcc') → tk.Molecule[source]

Create an OpenFF Molecule from a SMILES string and optional geometry.

Constructs an OpenFF Molecule from the provided SMILES string, adds conformers based on the provided geometry (if any), assigns partial charges using the specified method or provided partial charges, and applies charge scaling.

Parameters:

  • smile (str) – The SMILES string of the molecule.

  • geometry (Union[pymatgen.core.Molecule, str, Path, None], optional) – The geometry to use for adding conformers. Can be a Pymatgen Molecule, file path, or None.

  • charge_scaling (float, optional) – The scaling factor for partial charges. Default is 1.

  • partial_charges (Union[List[float], None], optional) – A list of partial charges to assign, or None to use the charge method.

  • backup_charge_method (str, optional) – The backup charge method to use if partial charges are not provided. Default is “am1bcc”.

Returns:

The created OpenFF Molecule.

Return type:

tk.Molecule

get_atom_map(inferred_mol: tk.Molecule, openff_mol: tk.Molecule) → tuple[bool, dict[int, int]][source]

Compute an atom mapping between two OpenFF Molecules.

Attempts to find an isomorphism between the molecules, considering various matching criteria such as formal charges, stereochemistry, and bond orders. Returns the atom mapping if an isomorphism is found, otherwise returns an empty mapping.

Parameters:

  • inferred_mol (tk.Molecule) – The first OpenFF Molecule.

  • openff_mol (tk.Molecule) – The second OpenFF Molecule.

Returns:

A tuple containing a boolean indicating if an

isomorphism was found and a dictionary representing the atom mapping.

Return type:

Tuple[bool, Dict[int, int]]

infer_openff_mol(mol_geometry: Molecule) → tk.Molecule[source]

Infer an OpenFF Molecule from a Pymatgen Molecule.

Constructs a MoleculeGraph from the Pymatgen Molecule using the OpenBabelNN local environment strategy and extends metal edges. Converts the resulting MoleculeGraph to an OpenFF Molecule using mol_graph_to_openff_mol.

Parameters:

mol_geometry (pymatgen.core.Molecule) – The Pymatgen Molecule to infer from.

Returns:

The inferred OpenFF Molecule.

Return type:

tk.Molecule

mol_graph_from_openff_mol(molecule: tk.Molecule) → MoleculeGraph[source]

This is designed to closely mirror the graph structure generated by tk.Molecule.to_networkx.

Parameters:

molecule (tk.Molecule) – The OpenFF Molecule to convert.

Returns:

The converted MoleculeGraph.

Return type:

MoleculeGraph

mol_graph_to_openff_mol(mol_graph: MoleculeGraph) → tk.Molecule[source]

Convert a Pymatgen MoleculeGraph to an OpenFF Molecule.

Parameters:

mol_graph (MoleculeGraph) – The Pymatgen MoleculeGraph to be converted.

Returns:

The converted OpenFF Molecule.

Return type:

tk.Molecule

pymatgen.io.optimade module

This module provides conversion between structure entries following the OPTIMADE (https://optimade.org) standard and pymatgen Structure objects.

The code is adapted from the optimade.adapters.structures.pymatgen module in optimade-python-tools (https://github.com/Materials-Consortia/optimade-python-tools), and aims to work without requiring the explicit installation of the optimade-python-tools.

class OptimadeStructureAdapter[source]

Bases: object

Adapter serves as a bridge between OPTIMADE structures and pymatgen objects.

static get_optimade_structure(structure: Structure | IStructure, **kwargs) → dict[str, str | dict[str, Any]][source]

Get a dictionary in the OPTIMADE Structure format from a pymatgen structure or molecule.

Parameters:

  • structure (Structure) – pymatgen Structure

  • **kwargs – passed to the ASE Atoms constructor

Returns:

A dictionary serialization of the structure in the OPTIMADE format.

static get_structure(resource: dict) → Structure[source]

Get pymatgen structure from an OPTIMADE structure resource.

Parameters:

resource – OPTIMADE structure resource as a dictionary, JSON string, or the corresponding attributes dictionary (i.e., resource[“attributes”]).

Returns:

Equivalent pymatgen Structure

Return type:

Structure

pymatgen.io.packmol module

This module provides a pymatgen I/O interface to PACKMOL.

  • PackmolSet provides a “run” method to run PACKMOL locally.

  • PackmolBoxGen provides “get_input_set” for packing molecules into a box,

which returns a PackmolSet object.

For the run() method to work, you need to install the PACKMOL package. See https://m3g.iqm.unicamp.br/packmol for download and setup instructions. After installation, you may need to add the path of the PACKMOL executable to the PATH environment variable.

Note that PACKMOL versions prior to 20.3.0 do not support paths with spaces.

class PackmolBoxGen(tolerance: float = 2.0, seed: int = 1, control_params: dict | None = None, inputfile: PathLike = 'packmol.inp', outputfile: PathLike = 'packmol_out.xyz', stdoutfile: PathLike = 'packmol.stdout')[source]

Bases: InputGenerator

Generator for a Packmol InputSet that packs one or more molecules into a rectangular simulation box.

Instantiate a PackmolBoxGen class. The init method defines simulations parameters like filenames, random seed, tolerance, etc.

Parameters:

  • tolerance (float) – Tolerance for packmol, in Å.

  • seed (int) – Random seed for packmol. Use 1 (default) for deterministic output, or -1 to generate a new random seed from the current time.

  • inputfile (PathLike) – Path to the input file. Default to “packmol.inp”.

  • outputfile (PathLike) – Path to the output file. Default to “packmol_out.xyz”.

  • stdoutfile (PathLike) – Path to the file where stdout will be recorded. Default to “packmol.stdout”.

get_input_set(molecules: list[dict], box: list[float] | None = None) → PackmolSet[source]

Generate a Packmol InputSet for a set of molecules.

Parameters:

  • molecules (list[dict]) –

    Information about molecules to pack into the box. Each dict requires three keys:

    1. ”name” - the structure name.

    2. ”number” - the number of that molecule to pack into the box.

    3. ”coords” - Coordinates in the form of either a Molecule

      object or a path to a file.

    Example

    {

    “name”: “water”, “number”: 500, “coords”: “/path/to/input/file.xyz”,

    }

  • box (list[float]) – Box dimensions xlo, ylo, zlo, xhi, yhi, zhi, in Å. If set to None (default), pymatgen will estimate the required box size based on the volumes of the provided molecules.

Returns:

PackmolSet

class PackmolSet(inputs: dict[PathLike, str | InputFile] | None = None, **kwargs)[source]

Bases: InputSet

InputSet for the PACKMOL software. This class defines several attributes related to.

Instantiate an InputSet.

Parameters:

  • inputs – The core mapping of filename: file contents that defines the InputSet data. This should be a dict where keys are filenames and values are InputFile objects or strings representing the entire contents of the file. If a value is not an InputFile object nor a str, but has a __str__ method, this str representation of the object will be written to the corresponding file. This mapping will become the .inputs attribute of the InputSet.

  • **kwargs – Any kwargs passed will be set as class attributes e.g. InputSet(inputs={}, foo=’bar’) will make InputSet.foo == ‘bar’.

classmethod from_directory(directory: PathLike) → None[source]

Construct an InputSet from a directory of one or more files.

Parameters:

directory (PathLike) – Directory to read input files from.

run(path: PathLike, timeout: float = 30) → None[source]

Run PACKMOL and write out the packed structure.

Parameters:

  • path (PathLike) – The path in which packmol input files are located.

  • timeout (float) – Timeout in seconds.

Raises:

  • ValueError – if packmol does not succeed in packing the box.

  • TimeoutExpiredError – if packmol does not finish within the timeout.

pymatgen.io.phonopy module

Module for interfacing with phonopy, see https://atztogo.github.io/phonopy/.

eigvec_to_eigdispl(eig_vec, q, frac_coords, mass)[source]

Converts a single eigenvector to an eigendisplacement in the primitive cell according to the formula:

exp(2*pi*i*(frac_coords dot q) / sqrt(mass) * v

Compared to the modulation option in phonopy, here all the additional multiplicative and phase factors are set to 1.

Parameters:

  • v – the vector that should be converted. A 3D complex numpy array.

  • q – the q point in fractional coordinates

  • frac_coords – the fractional coordinates of the atom

  • mass – the mass of the atom

get_complete_ph_dos(partial_dos_path, phonopy_yaml_path)[source]

Create a pymatgen CompletePhononDos from a partial_dos.dat and phonopy.yaml files. The second is produced when generating a Dos and is needed to extract the structure.

Parameters:

  • partial_dos_path – path to the partial_dos.dat file.

  • phonopy_yaml_path – path to the phonopy.yaml file.

get_displaced_structures(pmg_structure, atom_disp=0.01, supercell_matrix=None, yaml_fname=None, **kwargs)[source]

Generate a set of symmetrically inequivalent displaced structures for phonon calculations.

Parameters:

  • pmg_structure (Structure) – A pymatgen structure object.

  • atom_disp (float) – Atomic displacement. Default is 0.01 $\AA$.

  • supercell_matrix (3x3 array) – Scaling matrix for supercell.

  • yaml_fname (str) – If not None, it represents the full path to the outputting displacement YAML file, e.g. disp.yaml.

  • **kwargs – Parameters used in Phonopy.generate_displacement method.

Returns:

A list of symmetrically inequivalent structures with displacements, in which the first element is the perfect supercell structure.

get_gruneisen_ph_bs_symm_line(gruneisen_path, structure=None, structure_path=None, labels_dict=None, fit=False)[source]

Create a pymatgen GruneisenPhononBandStructure from a band.yaml file. The labels will be extracted from the dictionary, if present. If the ‘eigenvector’ key is found the eigendisplacements will be calculated according to the formula: \exp(2*pi*i*(frac_coords \dot q) / sqrt(mass) * v

and added to the object.

Parameters:

  • gruneisen_path – path to the band.yaml file

  • structure – pymaten Structure object

  • structure_path – path to a structure file (e.g., POSCAR)

  • labels_dict – dict that links a qpoint in frac coords to a label.

  • fit – Substitute Grueneisen parameters close to the gamma point with points obtained from a fit to a spline if the derivate from a smooth curve (i.e. if the slope changes by more than 200% in the range of 10% around the gamma point). These derivations occur because of very small frequencies (and therefore numerical inaccuracies) close to gamma.

get_gruneisenparameter(gruneisen_path, structure=None, structure_path=None) → GruneisenParameter[source]

Get Gruneisen object from gruneisen.yaml file, as obtained from phonopy (Frequencies in THz!). The order is structure > structure path > structure from gruneisen dict. Newer versions of phonopy include the structure in the YAML file, the structure/structure_path is kept for compatibility.

Parameters:

  • gruneisen_path – Path to gruneisen.yaml file (frequencies have to be in THz!)

  • structure – pymatgen Structure object

  • structure_path – path to structure in a file (e.g., POSCAR)

Returns:

GruneisenParameter

get_gs_ph_bs_symm_line_from_dict(gruneisen_dict, structure=None, structure_path=None, labels_dict=None, fit=False) → GruneisenPhononBandStructureSymmLine[source]

Create a pymatgen GruneisenPhononBandStructure object from the dictionary extracted by the gruneisen.yaml file produced by phonopy. The labels will be extracted from the dictionary, if present. If the ‘eigenvector’ key is found the eigendisplacements will be calculated according to the formula:

exp(2*pi*i*(frac_coords \dot q) / sqrt(mass) * v

and added to the object. A fit algorithm can be used to replace diverging Gruneisen values close to gamma.

Parameters:

  • gruneisen_dict (dict) – the dictionary extracted from the gruneisen.yaml file

  • structure (Structure) – pymatgen structure object

  • structure_path – path to structure file

  • labels_dict (dict) – dict that links a qpoint in frac coords to a label. Its value will replace the data contained in the band.yaml.

  • fit (bool) – Substitute Grueneisen parameters close to the gamma point with points obtained from a fit to a spline if the derivate from a smooth curve (i.e. if the slope changes by more than 200% in the range of 10% around the gamma point). These derivations occur because of very small frequencies (and therefore numerical inaccuracies) close to gamma.

get_ph_bs_symm_line(bands_path, has_nac=False, labels_dict=None)[source]

Create a pymatgen PhononBandStructure from a band.yaml file. The labels will be extracted from the dictionary, if present. If the ‘eigenvector’ key is found the eigendisplacements will be calculated according to the formula: \exp(2*pi*i*(frac_coords \dot q) / sqrt(mass) * v

and added to the object.

Parameters:

  • bands_path – path to the band.yaml file

  • has_nac – True if the data have been obtained with the option –nac option. Default False.

  • labels_dict – dict that links a q-point in frac coords to a label.

get_ph_bs_symm_line_from_dict(bands_dict, has_nac=False, labels_dict=None) → PhononBandStructureSymmLine[source]

Create a pymatgen PhononBandStructure object from the dictionary extracted by the band.yaml file produced by phonopy. The labels will be extracted from the dictionary, if present. If the ‘eigenvector’ key is found the eigendisplacements will be calculated according to the formula:

exp(2*pi*i*(frac_coords \dot q) / sqrt(mass) * v

and added to the object.

Parameters:

  • bands_dict – the dictionary extracted from the band.yaml file

  • has_nac – True if the data have been obtained with the option –nac option. Default False.

  • labels_dict – dict that links a qpoint in frac coords to a label. Its value will replace the data contained in the band.yaml.

Returns:

the phonon band structure

Return type:

PhononBandStructure

get_ph_dos(total_dos_path)[source]

Create a pymatgen PhononDos from a total_dos.dat file.

Parameters:

total_dos_path – path to the total_dos.dat file.

get_phonon_band_structure_from_fc(structure: Structure | IStructure, supercell_matrix: np.ndarray, force_constants: np.ndarray, mesh_density: float = 100.0, **kwargs) → PhononBandStructure[source]

Get a uniform phonon band structure from phonopy force constants.

Parameters:

  • structure – A structure.

  • supercell_matrix – The supercell matrix used to generate the force constants.

  • force_constants – The force constants in phonopy format.

  • mesh_density – The density of the q-point mesh. See the docstring for the mesh argument in Phonopy.init_mesh() for more details.

  • **kwargs – Additional kwargs passed to the Phonopy constructor.

Returns:

The uniform phonon band structure.

get_phonon_band_structure_symm_line_from_fc(structure: Structure | IStructure, supercell_matrix: np.ndarray, force_constants: np.ndarray, line_density: float = 20.0, symprec: float = 0.01, **kwargs) → PhononBandStructureSymmLine[source]

Get a phonon band structure along a high symmetry path from phonopy force constants.

Parameters:

  • structure – A structure.

  • supercell_matrix – The supercell matrix used to generate the force constants.

  • force_constants – The force constants in phonopy format.

  • line_density – The density along the high symmetry path.

  • symprec – Symmetry precision passed to phonopy and used for determining the band structure path.

  • **kwargs – Additional kwargs passed to the Phonopy constructor.

Returns:

The line mode band structure.

get_phonon_dos_from_fc(structure: Structure | IStructure, supercell_matrix: np.ndarray, force_constants: np.ndarray, mesh_density: float = 100.0, num_dos_steps: int = 200, **kwargs) → CompletePhononDos[source]

Get a projected phonon density of states from phonopy force constants.

Parameters:

  • structure – A structure.

  • supercell_matrix – The supercell matrix used to generate the force constants.

  • force_constants – The force constants in phonopy format.

  • mesh_density – The density of the q-point mesh. See the docstring for the mesh argument in Phonopy.init_mesh() for more details.

  • num_dos_steps – Number of frequency steps in the energy grid.

  • **kwargs – Additional kwargs passed to the Phonopy constructor.

Returns:

The density of states.

get_phonopy_structure(pmg_structure: Structure) → None[source]

Convert a pymatgen Structure object to a PhonopyAtoms object.

Parameters:

pmg_structure (pymatgen Structure) – A Pymatgen structure object.

get_pmg_structure(phonopy_structure: None) → Structure[source]

Convert a PhonopyAtoms object to pymatgen Structure object.

Parameters:

phonopy_structure (PhonopyAtoms) – A phonopy structure object.

get_structure_from_dict(dct) → Structure[source]

Extracts a structure from the dictionary extracted from the output files of phonopy like phonopy.yaml or band.yaml. Adds “phonopy_masses” in the site_properties of the structures. Compatible with older phonopy versions.

get_thermal_displacement_matrices(thermal_displacements_yaml='thermal_displacement_matrices.yaml', structure_path='POSCAR')[source]

Read “thermal_displacement_matrices.yaml” from phonopy and return a list of ThermalDisplacementMatrices objects.

Parameters:

  • thermal_displacements_yaml – path to thermal_displacement_matrices.yaml

  • structure_path – path to POSCAR.

Returns:

list[ThermalDisplacementMatrices]

pymatgen.io.prismatic module

Write Prismatic (https://prism-em.com) input files.

class Prismatic(structure: Structure | IStructure, comment: str = 'Generated by pymatgen')[source]

Bases: object

Write Prismatic (https://prism-em.com) input files. This is designed for STEM image simulation.

Parameters:

  • structure – pymatgen Structure

  • comment (str) – comment.

to_str() → str[source]
Returns:

Prismatic XYZ file. This is similar to XYZ format

but has specific requirements for extra fields, headers, etc.

Return type:

str

pymatgen.io.pwscf module

This module implements input and output processing from PWSCF.

class PWInput(structure, pseudo=None, control=None, system=None, electrons=None, ions=None, cell=None, kpoints_mode='automatic', kpoints_grid=(1, 1, 1), kpoints_shift=(0, 0, 0), format_options=None)[source]

Bases: object

Base input file class. Right now, only supports no symmetry and is very basic.

Initialize a PWSCF input file.

Parameters:

  • structure (Structure) – Input structure. For spin-polarized calculation, properties (e.g. {“starting_magnetization”: -0.5, “pseudo”: “Mn.pbe-sp-van.UPF”}) on each site is needed instead of pseudo (dict).

  • pseudo (dict) – A dict of the pseudopotentials to use. Default to None.

  • control (dict) – Control parameters. Refer to official PWSCF doc on supported parameters. Default to {“calculation”: “scf”}

  • system (dict) – System parameters. Refer to official PWSCF doc on supported parameters. Default to None, which means {}.

  • electrons (dict) – Electron parameters. Refer to official PWSCF doc on supported parameters. Default to None, which means {}.

  • ions (dict) – Ions parameters. Refer to official PWSCF doc on supported parameters. Default to None, which means {}.

  • cell (dict) – Cell parameters. Refer to official PWSCF doc on supported parameters. Default to None, which means {}.

  • kpoints_mode (str) – Kpoints generation mode. Default to automatic.

  • kpoints_grid (sequence) – The kpoint grid. Default to (1, 1, 1).

  • kpoints_shift (sequence) – The shift for the kpoints. Defaults to (0, 0, 0).

  • format_options (dict) –

    Formatting options when writing into a string. Can be used to specify e.g., the number of decimal places (including trailing zeros) for real-space coordinate values (atomic positions, cell parameters). Defaults to None, in which case the following default values are used (so as to maintain backwards compatibility): {“indent”: 2, “kpoints_crystal_b_indent”: 1,

    ”coord_decimals”: 6, “atomic_mass_decimals”: 4, “kpoints_grid_decimals”: 4}.

as_dict()[source]

Create a dictionary representation of a PWInput object.

Returns:

dict

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

Load a PWInput object from a dictionary.

Parameters:

dct (dict) – dictionary with PWInput data

Returns:

PWInput object

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

Reads an PWInput object from a file.

Parameters:

filename (str | Path) – Filename for file

Returns:

PWInput object

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

Reads an PWInput object from a string.

Parameters:

string (str) – PWInput string

Returns:

PWInput object

static proc_val(key, val)[source]

Static helper method to convert PWINPUT parameters to proper type, e.g. integers, floats, etc.

Parameters:

  • key – PWINPUT parameter key

  • val – Actual value of PWINPUT parameter.

write_file(filename)[source]

Write the PWSCF input file.

Parameters:

filename (str) – The string filename to output to.

exception PWInputError[source]

Bases: BaseException

Error for PWInput.

class PWOutput(filename)[source]

Bases: object

Parser for PWSCF output file.

Parameters:

filename (str) – Filename.

property final_energy: float[source]

The final energy from the PW output.

get_celldm(idx: int)[source]
Parameters:

idx (int) – index.

Returns:

Cell dimension along index

property lattice_type: int[source]

The lattice type.

patterns: ClassVar[dict[str, str]] = {'celldm1': 'celldm\\(1\\)=\\s+([\\d\\.]+)\\s', 'celldm2': 'celldm\\(2\\)=\\s+([\\d\\.]+)\\s', 'celldm3': 'celldm\\(3\\)=\\s+([\\d\\.]+)\\s', 'celldm4': 'celldm\\(4\\)=\\s+([\\d\\.]+)\\s', 'celldm5': 'celldm\\(5\\)=\\s+([\\d\\.]+)\\s', 'celldm6': 'celldm\\(6\\)=\\s+([\\d\\.]+)\\s', 'ecut': 'kinetic\\-energy cutoff\\s+=\\s+([\\d\\.\\-]+)\\s+Ry', 'energies': 'total energy\\s+=\\s+([\\d\\.\\-]+)\\sRy', 'lattice_type': 'bravais\\-lattice index\\s+=\\s+(\\d+)', 'nkpts': 'number of k points=\\s+([\\d]+)'}[source]
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.

pymatgen.io.res module

Provides parsing and read/write support for ShelX .res files as produced by the AIRSS code.

Converting from and back to pymatgen objects is expected to be reversible, i.e. you should get the same Structure or ComputedStructureEntry back. On the other hand, converting from and back to a string/file is not guaranteed to be reversible, i.e. a diff on the output would not be empty. The difference should be limited to whitespace, float precision, and the REM entries.

class AirssProvider(res: Res, parse_rems: Literal['gentle', 'strict'] = 'gentle')[source]

Bases: ResProvider

Provides access to the res file as does ResProvider. This class additionally provides access to fields in the TITL entry and various other fields found in the REM entries that AIRSS puts in the file. Values in the TITL entry that AIRSS could not get end up as 0. If the TITL entry is malformed, empty, or missing then attempting to construct this class from a res file will raise a ResError.

While AIRSS supports a number of geometry and energy solvers, CASTEP is the default. As such, fetching the information from the REM entries is only supported if AIRSS was used with CASTEP. The other properties that get put in the TITL should still be accessible even if CASTEP was not used.

The parse_rems attribute controls whether functions that fail to retrieve information from the REM entries should return None. If this is set to "strict", then a ParseError may be raised, but the return value will not be None. If it is set to "gentle", then None will be returned instead of raising an exception. This setting applies to all methods of this class that are typed to return an Optional type. Default is "gentle".

The from_str() and from_file() methods should be used instead of constructing this directly.

property appearances: int[source]

This is sometimes the number of times a structure was found in an AIRSS search. Using the cryan tool that comes with AIRSS may be a better approach than relying on this property.

as_dict(verbose: bool = True) → dict[str, Any][source]

Get dict with title fields, structure and rems of this AirssProvider.

property energy: float[source]

Energy of the structure. With CASTEP, this is usually the enthalpy and is in eV.

property entry: ComputedStructureEntry[source]

This res file as a ComputedStructureEntry.

classmethod from_file(filename: str | Path, parse_rems: Literal['gentle', 'strict'] = 'gentle') → Self[source]

Construct a Provider from a file.

classmethod from_str(string: str, parse_rems: Literal['gentle', 'strict'] = 'gentle') → Self[source]

Construct a Provider from a string.

get_airss_version() → tuple[str, date] | None[source]

Retrieves the version of AIRSS that was used along with the build date (not compile date).

Returns:

tuple[str, date] (version string, date)

get_castep_version() → str | None[source]

Retrieves the version of CASTEP that the res file was computed with from the REM entries.

Returns:

version string

get_cut_grid_gmax_fsbc() → tuple[float, float, float, str] | None[source]

Retrieves the cut-off energy, grid scale, Gmax, and finite basis set correction setting from the REM entries.

Returns:

(cut-off, grid scale, Gmax, fsbc)

Return type:

tuple[float, float, float, str]

get_func_rel_disp() → tuple[str, str, str] | None[source]

Retrieves the functional, relativity scheme, and dispersion correction from the REM entries.

Returns:

(functional, relativity, dispersion)

Return type:

tuple[str, str, str]

get_mpgrid_offset_nkpts_spacing() → tuple[tuple[int, int, int], tuple[float, float, float], int, float] | None[source]

Retrieves the MP grid, the grid offsets, number of kpoints, and maximum kpoint spacing.

Returns: (MP grid), (offsets), No. kpts, max spacing

get_pspots() → dict[str, str][source]

Retrieves the OTFG pseudopotential string that can be used to generate the pseudopotentials used in the calculation.

Returns:

dict[specie, potential]

get_run_start_info() → tuple[date, str] | None[source]

Retrieves the run start date and the path it was started in from the REM entries.

Returns:

(date, path)

Return type:

tuple[date, str]

property integrated_absolute_spin_density: float[source]

Corresponds to the last Integrated |Spin Density| in the CASTEP file.

property integrated_spin_density: float[source]

Corresponds to the last Integrated Spin Density in the CASTEP file.

property pressure: float[source]

Pressure for the run. This is in GPa if CASTEP was used.

property seed: str[source]

The seed name, typically also the name of the res file.

property spacegroup_label: str[source]

The Hermann-Mauguin notation of the spacegroup with ascii characters. So no. 225 would be Fm-3m, and no. 194 would be P6_3/mmc.

property volume: float[source]

Volume of the structure. This is in cubic Angstroms if CASTEP was used.

class AirssTITL(seed: 'str', pressure: 'float', volume: 'float', energy: 'float', integrated_spin_density: 'float', integrated_absolute_spin_density: 'float', spacegroup_label: 'str', appearances: 'int')[source]

Bases: object

appearances: int[source]
energy: float[source]
integrated_absolute_spin_density: float[source]
integrated_spin_density: float[source]
pressure: float[source]
seed: str[source]
spacegroup_label: str[source]
volume: float[source]
class Ion(specie: 'str', specie_num: 'int', pos: 'tuple[float, float, float]', occupancy: 'float', spin: 'float | None')[source]

Bases: object

occupancy: float[source]
pos: tuple[float, float, float][source]
specie: str[source]
specie_num: int[source]
spin: float | None[source]
class Res(TITL: AirssTITL | None, REMS: list[str], CELL: ResCELL, SFAC: ResSFAC)[source]

Bases: object

Representation for the data in a res file.

CELL: ResCELL[source]
REMS: list[str][source]
SFAC: ResSFAC[source]
TITL: AirssTITL | None[source]
class ResCELL(unknown_field_1: 'float', a: 'float', b: 'float', c: 'float', alpha: 'float', beta: 'float', gamma: 'float')[source]

Bases: object

a: float[source]
alpha: float[source]
b: float[source]
beta: float[source]
c: float[source]
gamma: float[source]
unknown_field_1: float[source]
exception ResError[source]

Bases: ValueError

This exception indicates a problem was encountered while trying to retrieve a value or perform an action that a provider for the res file does not support.

class ResIO[source]

Bases: object

Convenience methods for converting a Structure or ComputedStructureEntry to/from a string or file in the res format as used by AIRSS.

Note: Converting from and back to pymatgen objects is expected to be reversible, i.e. you should get the same Structure or ComputedStructureEntry back. On the other hand, converting from and back to a string/file is not guaranteed to be reversible, i.e. a diff on the output would not be empty. The difference should be limited to whitespace, float precision, and the REM entries.

If the TITL entry doesn’t exist or is malformed or empty, then you can only get a Structure. Attempting to get an Entry will raise a ResError.

classmethod entry_from_file(filename: str) → ComputedStructureEntry[source]

Produce a pymatgen ComputedStructureEntry from a res file.

classmethod entry_from_str(string: str) → ComputedStructureEntry[source]

Produce a pymatgen ComputedStructureEntry from contents of a res file.

classmethod entry_to_file(entry: ComputedStructureEntry, filename: str) → None[source]

Write a pymatgen ComputedStructureEntry to a res file.

classmethod entry_to_str(entry: ComputedStructureEntry) → str[source]

Produce the contents of a res file from a pymatgen ComputedStructureEntry.

classmethod structure_from_file(filename: str) → Structure[source]

Produces a pymatgen Structure from a res file.

classmethod structure_from_str(string: str) → Structure[source]

Produces a pymatgen Structure from contents of a res file.

classmethod structure_to_file(structure: Structure | IStructure, filename: str) → None[source]

Write a pymatgen Structure to a res file.

classmethod structure_to_str(structure: Structure | IStructure) → str[source]

Produce the contents of a res file from a pymatgen Structure.

exception ResParseError[source]

Bases: ParseError

This exception indicates a problem was encountered during parsing due to unexpected formatting.

class ResParser[source]

Bases: object

Parser for the ShelX res file.

class ResProvider(res: Res)[source]

Bases: MSONable

Access elements of the RES file as familiar pymatgen objects.

The from_str() and from_file() methods should be used instead of constructing this directly.

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

Construct a Provider from a file.

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

Construct a Provider from a string.

property lattice: Lattice[source]

Construct a Lattice from the res file.

property rems: list[str][source]

The full list of REM entries contained within the res file.

property sites: list[PeriodicSite][source]

Construct a list of PeriodicSites from the res file.

property structure: Structure[source]

Construct a Structure from the res file.

class ResSFAC(species: 'list[str]', ions: 'list[Ion]')[source]

Bases: object

ions: list[Ion][source]
species: list[str][source]
class ResWriter(entry: Structure | IStructure | ComputedStructureEntry)[source]

Bases: object

This class provides a means to write a Structure or ComputedStructureEntry to a res file.

This class can be constructed from either a pymatgen Structure or ComputedStructureEntry object.

property string: str[source]

The contents of the res file.

write(filename: str) → None[source]

Write the res data to a file.

pymatgen.io.shengbte module

This module implements reading and writing of ShengBTE CONTROL files.

class Control(ngrid: list[int] | None = None, temperature: float | dict[str, float] = 300, **kwargs)[source]

Bases: MSONable, dict

Read, update, and write ShengBTE CONTROL files. See https://bitbucket.org/sousaw/shengbte/src/master/ for more detailed description and default values of CONTROL arguments.

Parameters:

  • ngrid – Reciprocal space grid density as a list of 3 ints.

  • temperature – The temperature to calculate the lattice thermal conductivity for. Can be given as a single float, or a dictionary with the keys “min”, “max”, “step”.

  • **kwargs –

    Other ShengBTE parameters. Several parameters are required for ShengBTE to run - we have listed these parameters below: - nelements (int): number of different elements in the compound - natoms (int): number of atoms in the unit cell - lattvec (size 3x3 array): real-space lattice vectors, in units of lfactor - lfactor (float): unit of measurement for lattice vectors (nm).

    I.e., set to 0.1 if lattvec given in Angstrom.

    • types (size natom list): a vector of natom integers, ranging from 1 to nelements, assigning an element to each atom in the system

    • elements (size natom list): a vector of element names

    • positions (size natomx3 array): atomic positions in lattice coordinates

    • scell (size 3 list): supercell sizes along each crystal axis used for the 2nd-order force constant calculation.

allocations_keys = ('nelements', 'natoms', 'ngrid', 'norientations')[source]
as_dict()[source]

Get MSONable dict.

crystal_keys = ('lfactor', 'lattvec', 'types', 'elements', 'positions', 'masses', 'gfactors', 'epsilon', 'born', 'scell', 'orientations')[source]
data_keys = ('nelements', 'natoms', 'ngrid', 'lattvec', 'types', 'elements', 'positions', 'scell')[source]
flags_keys = ('nonanalytic', 'convergence', 'isotopes', 'autoisotopes', 'nanowires', 'onlyharmonic', 'espresso')[source]
classmethod from_dict(control_dict: dict) → Self[source]

Write a CONTROL file from a Python dictionary. Description and default parameters can be found at https://bitbucket.org/sousaw/shengbte/src/master/. Note some parameters are mandatory. Optional parameters default here to None and will not be written to file.

Parameters:

control_dict – A Python dictionary of ShengBTE input parameters.

classmethod from_file(filepath: str) → Self[source]

Read a CONTROL namelist file and output a ‘Control’ object.

Parameters:

filepath – Path of the CONTROL file.

Returns:

‘Control’ object with parameters instantiated.

classmethod from_structure(structure: Structure | IStructure, reciprocal_density: int | None = 50000, **kwargs) → Self[source]

Get a ShengBTE control object from a structure.

Parameters:

  • structure – A structure object.

  • reciprocal_density – If not None, the q-point grid (“ngrid”) will be set using this density.

  • kwargs – Additional options to be passed to the Control constructor. See the docstring of the __init__ method for more details

Returns:

A ShengBTE control object.

get_structure() → Structure[source]

Get a pymatgen Structure from a ShengBTE control object.

The control object must have the “lattvec”, “types”, “elements”, and “positions” settings otherwise an error will be thrown.

Returns:

The structure.

params_keys = ('t', 't_min', 't_max', 't_step', 'omega_max', 'scalebroad', 'rmin', 'rmax', 'dr', 'maxiter', 'nticks', 'eps')[source]
required_params = ('nelements', 'natoms', 'ngrid', 'lattvec', 'types', 'elements', 'positions', 'scell')[source]
to_file(filename: str = 'CONTROL') → None[source]

Write ShengBTE CONTROL file from ‘Control’ object.

Parameters:

filename – A file name.

pymatgen.io.template module

This module defines a simple concrete implementation of the InputGenerator class that can be used to facilitate writing large numbers of input files based on a template.

class TemplateInputGen[source]

Bases: InputGenerator

Concrete implementation of InputGenerator that is based on a single template input file with variables.

This class is provided as a low-barrier way to support new codes and to provide an intuitive way for users to transition from manual scripts to pymatgen I/O classes.

get_input_set(template: PathLike, variables: dict | None = None, filename: PathLike = 'input.txt') → InputSet[source]
Parameters:

  • template – the input file template containing variable strings to be replaced.

  • variables – dict of variables to replace in the template. Keys are the text to replaced with the values, e.g. {“TEMPERATURE”: 298} will replace the text $TEMPERATURE in the template. See Python’s Template.safe_substitute() method documentation for more details.

  • filename – the file to be written.

pymatgen.io.wannier90 module

Modules for working with wannier90 input and output.

class Unk(ik: int, data: ndarray)[source]

Bases: object

Object representing the data in a UNK file.

ik[source]

Index of kpoint for this file.

Type:

int

data[source]

Numpy array that contains the wavefunction data in the UNK file. The shape should be (nbnd, ngx, ngy, ngz) for regular calculations and (nbnd, 2, ngx, ngy, ngz) for noncollinear calculations.

Type:

numpy.ndarray

is_noncollinear[source]

True if data is from a noncollinear calculation.

Type:

bool

nbnd[source]

Number of bands in data.

Type:

int

ng[source]

Sequence of three integers that correspond to the grid size of the given data. The definition is ng = (ngx, ngy, ngz).

Type:

tuple

Initialize Unk class.

Parameters:

  • ik (int) – index of the kpoint UNK file is for

  • data (np.ndarray) – data from the UNK file that has shape (nbnd, ngx, ngy, ngz) or (nbnd, 2, ngx, ngy, ngz) if noncollinear

property data: ndarray[source]

contains the wavefunction data in the UNK file. The shape should be (nbnd, ngx, ngy, ngz) for regular calculations and (nbnd, 2, ngx, ngy, ngz) for noncollinear calculations.

Type:

np.ndarray

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

Reads the UNK data from file.

Parameters:

filename (str) – path to UNK file to read

Returns:

Unk object

ik: int[source]
is_noncollinear: bool[source]
nbnd: int[source]
ng: Sequence[int][source]
write_file(filename: str) → None[source]

Write the UNK file.

Parameters:

filename (str) – path to UNK file to write, the name should have the form ‘UNKXXXXX.YY’ where XXXXX is the kpoint index (Unk.ik) and YY is 1 or 2 for the spin index or NC if noncollinear

pymatgen.io.xcrysden module

Support for reading XCrysDen files.

class XSF(structure: Structure | IStructure)[source]

Bases: object

Parse XCrysden files.

Parameters:

structure (Structure) – Structure object.

classmethod from_str(input_string: str, cls_=None) → Self[source]

Initialize a Structure object from a string with data in XSF format.

Parameters:
Example file:

CRYSTAL see (1) these are primitive lattice vectors (in Angstroms) PRIMVEC 0.0000000 2.7100000 2.7100000 see (2) 2.7100000 0.0000000 2.7100000 2.7100000 2.7100000 0.0000000

these are conventional lattice vectors (in Angstroms) CONVVEC 5.4200000 0.0000000 0.0000000 see (3) 0.0000000 5.4200000 0.0000000 0.0000000 0.0000000 5.4200000

these are atomic coordinates in a primitive unit cell (in Angstroms) PRIMCOORD 2 1 see (4) 16 0.0000000 0.0000000 0.0000000 see (5) 30 1.3550000 -1.3550000 -1.3550000

to_str(atom_symbol: bool = True) → str[source]

Get a string with the structure in XSF format See http://www.xcrysden.org/doc/XSF.html.

Parameters:

atom_symbol (bool) – Uses atom symbol instead of atomic number. Defaults to True.

pymatgen.io.xr module

This module provides input and output mechanisms for the xr file format, which is a modified CSSR file format and, for example, used in GULP. In particular, the module makes it easy to remove shell positions from relaxations that employed core-shell models.

class Xr(structure: Structure)[source]

Bases: object

For working with XR files.

Parameters:

structure (Structure | IStructure) – Structure object to create the Xr object.

classmethod from_file(filename: str | Path, use_cores: bool = True, thresh: float = 0.0001) → Self[source]

Reads an xr-formatted file to create an Xr object.

Parameters:

  • filename (str) – name of file to read from.

  • use_cores (bool) – use core positions and discard shell positions if set to True (default). Otherwise, use shell positions and discard core positions.

  • thresh (float) – relative threshold for consistency check between cell parameters (lengths and angles) from header information and cell vectors, respectively.

Returns:

Xr object corresponding to the input

file.

Return type:

xr (Xr)

classmethod from_str(string: str, use_cores: bool = True, thresh: float = 0.0001) → Self[source]

Creates an Xr object from a string representation.

Parameters:

  • string (str) – string representation of an Xr object.

  • use_cores (bool) – use core positions and discard shell positions if set to True (default). Otherwise, use shell positions and discard core positions.

  • thresh (float) – relative threshold for consistency check between cell parameters (lengths and angles) from header information and cell vectors, respectively.

Returns:

Xr object corresponding to the input

string representation.

Return type:

xr (Xr)

write_file(filename: str | Path) → None[source]

Write out an xr file.

Parameters:

filename (str) – name of the file to write to.

pymatgen.io.xyz module

Module implementing an XYZ file object class.

class XYZ(mol: Molecule | Structure | Sequence[Molecule | Structure], coord_precision: int = 6)[source]

Bases: object

Basic class for importing and exporting Molecules or Structures in XYZ format.

Note

Exporting periodic structures in the XYZ format will lose information about the periodicity. Essentially, only Cartesian coordinates are written in this format and no information is retained about the lattice.

Parameters:

  • mol (Molecule | Structure) – Input molecule or structure or list thereof.

  • coord_precision – Precision to be used for coordinates.

property all_molecules: list[Molecule][source]

All the frames of molecule associated with this XYZ.

as_dataframe()[source]

Generate a coordinates data frame with columns: atom, x, y, and z In case of multiple frame XYZ, returns the last frame.

Returns:

pandas.DataFrame

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

Creates XYZ object from a file.

Parameters:

filename – XYZ filename

Returns:

XYZ object

classmethod from_str(contents: str) → Self[source]

Creates XYZ object from a string.

Parameters:

contents – String representing an XYZ file.

Returns:

XYZ object

property molecule: Molecule[source]

Molecule associated with this XYZ. In case of multi-frame XYZ, returns the last frame.

write_file(filename: str) → None[source]

Write XYZ file.

Parameters:

filename (str) – File name of output file.

pymatgen.io.zeopp module

Module implementing classes and functions to use Zeo++ by Maciej Haranczyk.

If using this module, cite the following paper on Zeo++: T.F. Willems, C.H. Rycroft, M. Kazi, J.C. Meza, and M. Haranczyk, Algorithms and tools for high-throughput geometry-based analysis of crystalline porous materials, Microporous and Mesoporous Materials, 149 (2012) 134-141.

Zeo++ Installation Steps:

A stable version of Zeo++ can be obtained from https://zeoplusplus.org. Instructions can be found at https://www.zeoplusplus.org/download.html

Zeo++ Post-Installation Checking:

  1. Go to pymatgen/io/tests and run “python test_zeoio.py” If Zeo++ python bindings are properly installed, the tests should pass. One or two tests will be skipped.

  1. Go to pymatgen/analysis/defects/tests and run “python test_point_defects.py”. Lots of tests will be skipped if GULP is not installed. But there should be no errors.

class ZeoCssr(structure: Structure)[source]

Bases: Cssr

ZeoCssr adds extra fields to CSSR sites to conform with Zeo++ input CSSR format. The coordinate system is rotated from xyz to zyx. This change aligns the pivot axis of pymatgen (z-axis) to pivot axis of Zeo++ (x-axis) for structural modifications.

Parameters:

structure – A structure to create ZeoCssr object.

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

Reads a CSSR file to a ZeoCssr object.

Parameters:

filename – Filename to read from.

Returns:

ZeoCssr object.

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

Reads a string representation to a ZeoCssr object.

Parameters:

string – A string representation of a ZeoCSSR.

Returns:

ZeoCssr object.

class ZeoVoronoiXYZ(mol)[source]

Bases: XYZ

Read Voronoi Nodes from XYZ file written by Zeo++. The sites have an additional column representing the voronoi node radius. The voronoi node radius is represented by the site property voronoi_radius.

Parameters:

mol – Input molecule holding the voronoi node information.

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

Creates XYZ object from a file.

Parameters:

filename – XYZ filename

Returns:

XYZ object

classmethod from_str(contents: str) → Self[source]

Creates Zeo++ Voronoi XYZ object from a string. from_string method of XYZ class is being redefined.

Parameters:

contents – String representing Zeo++ Voronoi XYZ file.

Returns:

ZeoVoronoiXYZ object

get_free_sphere_params(structure, rad_dict=None, probe_rad=0.1)[source]

Analyze the void space in the input structure using voronoi decomposition Calls Zeo++ for Voronoi decomposition.

Parameters:

  • structure – pymatgen Structure

  • rad_dict (optional) – Dictionary of radii of elements in structure. If not given, Zeo++ default values are used. Note: Zeo++ uses atomic radii of elements. For ionic structures, pass rad_dict with ionic radii

  • probe_rad (optional) – Sampling probe radius in Angstroms. Default is 0.1 A

Returns:

voronoi nodes as pymatgen Structure within the unit cell defined by the lattice of input structure voronoi face centers as pymatgen Structure within the unit cell defined by the lattice of input structure

get_high_accuracy_voronoi_nodes(structure, rad_dict, probe_rad=0.1)[source]

Analyze the void space in the input structure using high accuracy voronoi decomposition. Calls Zeo++ for Voronoi decomposition.

Parameters:

  • structure – pymatgen Structure

  • rad_dict (optional) – Dictionary of radii of elements in structure. If not given, Zeo++ default values are used. Note: Zeo++ uses atomic radii of elements. For ionic structures, pass rad_dict with ionic radii

  • probe_rad (optional) – Sampling probe radius in Angstroms. Default is 0.1 A

Returns:

voronoi nodes as pymatgen Structure within the unit cell defined by the lattice of input structure voronoi face centers as pymatgen Structure within the unit cell defined by the lattice of input structure

get_voronoi_nodes(structure, rad_dict=None, probe_rad=0.1)[source]

Analyze the void space in the input structure using voronoi decomposition Calls Zeo++ for Voronoi decomposition.

Parameters:

  • structure – pymatgen Structure

  • rad_dict (optional) – Dictionary of radii of elements in structure. If not given, Zeo++ default values are used. Note: Zeo++ uses atomic radii of elements. For ionic structures, pass rad_dict with ionic radii

  • probe_rad (optional) – Sampling probe radius in Angstroms. Default is 0.1 A

Returns:

voronoi nodes as pymatgen Structure within the unit cell defined by the lattice of input structure voronoi face centers as pymatgen Structure within the unit cell defined by the lattice of input structure