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

  • -----

  • block. (Duplicate check will not be performed if this is an 'Atoms') –

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(d)[source]

Construct a MSONable AdfKey object from the JSON dict.

Parameters:
  • d (dict) – A dict of saved attributes.

  • Returns

  • -------

  • adfkey (AdfKey) – An AdfKey object recovered from the JSON dict d.

classmethod from_str(string: str) AdfKey[source]

Construct an AdfKey object from the string.

Parameters:
  • string (str) – A string.

  • Returns

  • -------

  • adfkey (AdfKey) – 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

  • -----

  • returned. (Only the first block key will be) –

has_option(option)[source]

Return True if the option is included in this key.

Parameters:
  • option (str) – The option.

  • Returns

  • -------

  • has (bool) – True if the option can be found. Otherwise False will be returned.

has_subkey(subkey)[source]

Return True if this AdfKey contains the given subkey.

Parameters:
  • subkey (str or AdfKey) – A key name or an AdfKey object.

  • Returns

  • -------

  • has (bool) – True if this key contains the given key. Otherwise False.

is_block_key() bool[source]

Return True if this key is a block key.

property key[source]

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

remove_option(option)[source]

Remove an option.

Parameters:
  • option (str or int) – The name (str) or index (int) 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.

Attributes:

is_failedbool

True is the ADF job is terminated without success. Otherwise False.

is_internal_crashbool

True if the job is terminated with internal crash. Please read ‘TAPE13’ of the ADF manual for more detail.

errorstr

The error description.

run_typestr

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

final_energyfloat

The final molecule energy (a.u).

final_structureGMolecule

The final structure of the molecule.

energiesSized

The energy of each cycle.

structuresSized

The structure of each cycle If geometry optimization is performed.

frequenciesarray_like

The frequencies of the molecule.

normal_modesarray_like

The normal modes of the molecule.

freq_typestr

Either ‘Analytical’ or ‘Numerical’.

Initialization method.

param filename:

The ADF output file to parse.

type filename:

str

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.

param operation:

The target operation.

type operation:

str

param basis_set:

The basis set definitions for this task. Defaults to ‘DZ/Large’.

type basis_set:

AdfKey

param xc:

The exchange-correlation functionals. Defaults to PBE.

type xc:

AdfKey

param title:

The title of this ADF task.

type title:

str

param units:

The units. Defaults to Angstroms/Degree.

type units:

AdfKey

param geo_subkeys:

The subkeys for the block key ‘GEOMETRY’.

type geo_subkeys:

Sized

param scf:

The scf options.

type scf:

AdfKey

param other_directives:

User-defined directives.

type other_directives:

Sized

as_dict()[source]

A JSON-serializable dict representation of self.

classmethod from_dict(d)[source]

Construct a MSONable AdfTask object from the JSON dict.

Parameters:
  • d (dict) – A dict of saved attributes.

  • Returns

  • -------

  • task (AdfTask) – An AdfTask object recovered from the JSON dict d.

static get_default_basis_set()[source]

Returns: Default basis set.

static get_default_geo()[source]

Returns: ADFKey using default geometry.

static get_default_scf()[source]

Returns: ADF using default SCF.

static get_default_units()[source]

Returns: Default units.

static get_default_xc()[source]

Returns: ADFKey using default XC.

operations = {'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]
is_numeric(s) bool[source]

Return True is the string s is a numeric string.

Parameters:

s (str) – A string

Returns:

If True, s is a numeric string and can be converted to an int or a

float. Otherwise False will be returned.

Return type:

bool

pymatgen.io.ase module

This module provides conversion between the Atomic Simulation Environment 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, **kwargs) Atoms[source]

Returns ASE Atoms object from pymatgen structure or molecule.

Parameters:
  • structure (SiteCollection) – pymatgen Structure or Molecule

  • **kwargs – passed to the ASE Atoms constructor

Returns:

ASE Atoms object

Return type:

Atoms

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

Returns pymatgen molecule from ASE Atoms.

Parameters:
  • atoms – ASE Atoms object

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

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

Returns:

Equivalent pymatgen.core.structure.Molecule

Return type:

Molecule

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

Returns pymatgen structure from ASE Atoms.

Parameters:
  • atoms – ASE Atoms object

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

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

Returns:

Equivalent pymatgen Structure

Return type:

Structure

pymatgen.io.atat module

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

class Mcsqs(structure: Structure)[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.

Initializes with pymatgen Molecule or OpenBabel’s OBMol.

Parameters:

mol – pymatgen’s Molecule/IMolecule or OpenBabel OBMol

add_hydrogen()[source]

Add hydrogens (make all hydrogen explicit).

confab_conformers(forcefield='mmff94', freeze_atoms=None, rmsd_cutoff=0.5, energy_cutoff=50.0, conf_cutoff=100000, verbose=False)[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 (float) – 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, file_format='xyz', return_all_molecules=False)[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

static from_molecule_graph(mol)[source]

Read a molecule from a pymatgen MoleculeGraph object.

Parameters:

mol – pymatgen MoleculeGraph object.

Returns:

BabelMolAdaptor object

from_str(string_data, file_format='xyz')[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()[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='mmff94', steps=500)[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='mmff94', steps=50)[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]

Returns OpenBabel’s OBMol.

property pybel_mol[source]

Returns Pybel’s Molecule object.

property pymatgen_mol[source]

Returns pymatgen Molecule object.

remove_bond(idx1, idx2)[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='WeightedRotorSearch', forcefield='mmff94')[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, file_format='xyz')[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

Wrapper classes for Cif input and output from Structures.

class CifBlock(data, loops, header)[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)[source]

Reads CifBlock from string.

Parameters:

string – String representation.

Returns:

CifBlock

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

Bases: object

Reads and parses CifBlocks from a .cif file or string.

Parameters:
  • data (dict) – Of CifBlock objects.

  • orig_string (str) – The original cif string.

  • comment (str) – Comment string.

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

Reads CifFile from a filename.

Parameters:

filename – Filename

Returns:

CifFile

classmethod from_str(string) CifFile[source]

Reads CifFile from a string.

Parameters:

string – String representation.

Returns:

CifFile

class CifParser(filename: str | 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

Parses a CIF file. Attempts 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 (str) – CIF filename, gzipped or bzipped CIF files are fine too.

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

  • site_tolerance (float) – This tolerance is used to determine if two sites are sitting in 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()[source]

MSONable dict

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

Check whether a structure constructed from CIF passes sanity checks.

Parameters:

structure (Structure) – structure created from CIF

Returns:

If any check fails, on output, returns a human-readable str for the

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

Return type:

str | None

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.

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

Creates a CifParser from a string.

Parameters:
  • cif_string (str) – String representation of a CIF.

  • **kwargs – Passthrough of all kwargs supported by CifParser.

Returns:

CifParser

get_bibtex_string()[source]

Get BibTeX reference from CIF file. :param data:

Returns:

BibTeX string.

get_lattice(data, length_strings=('a', 'b', 'c'), angle_strings=('alpha', 'beta', 'gamma'), lattice_type=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, length_strings=('a', 'b', 'c'), angle_strings=('alpha', 'beta', 'gamma'), lattice_type=None)[source]

Take a dictionary of CIF data and returns a pymatgen Lattice object.

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 – The type of lattice. This is a string, and can be any of the following:

Returns:

Lattice object

get_magsymops(data)[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]

get_structures is deprecated! get_structures is deprecated and will be removed in 2024. Use parse_structures instead.The only difference is that primitive defaults to False in the new parse_structures method.So parse_structures(primitive=True) is equivalent to the old behavior of get_structures().

Deprecated. Use parse_structures instead. Only difference between the two methods is the default primitive=False in parse_structures. So parse_structures(primitive=True) is equivalent to the old behavior of get_structures().

get_symops(data)[source]

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

property has_errors[source]

Whether there are errors/warnings detected in CIF parsing.

static parse_magmoms(data, lattice=None)[source]

Parse atomic magnetic moments from data dictionary.

static parse_oxi_states(data)[source]

Parse oxidation states from data dictionary.

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) – Set to True to return primitive unit cells. Defaults to False. With magnetic CIF files, True will return primitive magnetic cell which may be larger than nuclear primitive cell.

  • symmetrized (bool) – If True, 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) – If False, site occupancy will not be checked, allowing unphysical occupancy != 1. Useful for experimental results in which occupancy was allowed to refine to unphysical values. Warning: unphysical site 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, 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 structures.

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[source]

CifFile associated with the CifWriter.

Type:

Returns

write_file(filename: str | Path, mode: Literal['w', 'a', 'wt', 'at'] = 'w') None[source]

Write the CIF file.

str2float(text)[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 VolumetricData(structure: Structure, data, distance_matrix=None, data_aug=None)[source]

Bases: MSONable

Simple volumetric object. Used to read LOCPOT/CHGCAR files produced by vasp as well as cube files produced by other codes.

structure[source]

Structure associated with the Volumetric Data object.

Type:

Structure

is_spin_polarized[source]

True if run is spin polarized.

Type:

bool

dim[source]

Tuple of dimensions of volumetric grid in each direction (nx, ny, nz).

Type:

tuple

data[source]

Actual data as a dict of {string: np.array}. The string are “total” and “diff”, in accordance to the output format of Vasp LOCPOT and CHGCAR files where the total spin density is written first, followed by the difference spin density.

Type:

dict

ngridpts[source]

Total number of grid points in volumetric data.

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 – Actual volumetric data. If the data is provided as in list format, it will be converted into an np.array automatically

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

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

copy()[source]

Copy of Volumetric object

classmethod from_cube(filename)[source]

Initialize the cube object and store the data as data.

Parameters:

filename (str) – of the cube to read

classmethod from_hdf5(filename, **kwargs)[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]

Returns 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=None)[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]

Writes 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) correspondisng 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: str | Path)[source]

Creates an InputFile object from a file.

Parameters:

path – Filename to read, including path.

Returns:

InputFile

abstract classmethod from_str(contents: str) InputFile[source]

Create an InputFile object from a string.

Parameters:

contents – The contents of the file as a single string

Returns:

InputFile

abstract get_str() str[source]

Return a string representation of an entire input file.

write_file(filename: str | 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.

abstract get_input_set() InputSet[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[str | Path, 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: str | Path)[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: str | Path, make_dir: bool = True, overwrite: bool = True, zip_inputs: bool = False)[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

This exception indicates 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)[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)[source]

Reads a CSSR file to a Cssr object.

Parameters:

filename (str) – Filename to read from.

Returns:

Cssr object.

classmethod from_str(string)[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).

and

-Nwchem2Fiesta class: to create the input files needed for a Fiesta run -Fiesta_run: run gw_fiesta and bse_fiesta -Localised Basis set reader

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]
Parameters:

BSE_dump – boolean

Returns:

set the “do_bse” variable to one in cell.in

dump_tddft_data_in_gw_run(tddft_dump=True)[source]
Parameters:

TDDFT_dump – boolean

Returns:

set the do_tddft variable to one in cell.in

classmethod from_dict(d)[source]
Parameters:

d – Dict representation

Returns:

FiestaInput

classmethod from_file(filename)[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)[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]

Returns 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]

Returns 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. :param auxiliary_folder: folder where the auxiliary basis sets are stored :param 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 :param nv_bse: number of valence bands :param nc_bse: number of conduction bands :param n_excitations: number of excitations :param 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 :param nv__band: number of valence bands to correct with GW :param nc_band: number of conduction bands to correct with GW :param n_iteration: number of iteration :param n_grid and dE_grid:: number of points and spacing in eV for correlation grid.

write_file(filename)[source]

Write FiestaInput to a file :param 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]

Performs BSE run.

classmethod from_dict(d)[source]
Parameters:

d – Dict representation

Returns:

FiestaRun

run()[source]

Performs 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

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.

the run method launches NWCHEM2FIESTA

as_dict()[source]

MSONable dict

classmethod from_dict(d)[source]
Parameters:

d – Dict representation.

Returns:

Nwchem2Fiesta

run()[source]

Performs 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

An object representing 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(d)[source]
Parameters:

d – dict

Returns:

GaussianInput

classmethod from_file(filename)[source]

Creates GaussianInput from a file.

Parameters:

filename – Gaussian input filename

Returns:

GaussianInput object

classmethod from_str(contents)[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]

Returns a z-matrix representation of the molecule.

property molecule[source]

Returns 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)[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

Methods: .. method:: to_input()

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, lamba) 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:

gaunip (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.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]

Returns JARVIS Atoms object from pymatgen structure.

Parameters:

structure – pymatgen Structure

Returns:

JARVIS Atoms object

static get_structure(atoms)[source]

Returns 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

Class for reading 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]

Boolean to indicate 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, header: str | None = None, version: str = 'LMASA-47')[source]

Bases: object

Class for parsing 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]

Returns 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)[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='CTRL', **kwargs)[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) LMTOCtrl[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]

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

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

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

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]

Returns: MSONable dict.

classmethod from_dict(d)[source]
Parameters:

d (dict) – Dict representation.

Returns:

NwInput

classmethod from_file(filename)[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)[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]

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

(ExcitationSpectrum) which can be plotted using

pymatgen.vis.plotters.SpectrumPlotter.

parse_tddft()[source]

Parses TDDFT roots. Adapted from nw_spectrum.py script.

Returns:

{
“singlet”: [
{

“energy”: float, “osc_strength: float

}

], “triplet”: [

{

“energy”: float

}

]

}

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]

Returns: 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(d)[source]
Parameters:

d (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)[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 = {'': '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 = {'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.packmol module

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

This adopts the minimal core I/O interface (see pymatgen/io/core). In this case, only a two classes are used. PackmolSet(InputSet) is the container class that provides a run() method for running packmol locally.

PackmolBoxGen(InputGenerator) provides a recipe 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 http://m3g.iqm.unicamp.br/packmol or http://leandro.iqm.unicamp.br/m3g/packmol/home.shtml for download and setup instructions. Note that packmol versions prior to 20.3.0 do not support paths with spaces. After installation, you may need to manually add the path of the packmol executable to the PATH environment variable.

class PackmolBoxGen(tolerance: float = 2.0, seed: int = 1, control_params: dict | None = None, inputfile: str | Path = 'packmol.inp', outputfile: str | Path = 'packmol_out.xyz', stdoutfile: str | Path = '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 – Tolerance for packmol, in Å.

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

  • inputfile – Path to the input file. Default to ‘packmol.inp’.

  • outputfile – Path to the output file. Default to ‘output.xyz’.

  • stdoutfile – 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

A list of dict containing 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: A list of 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.

class PackmolSet(inputs: dict[str | Path, 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: str | Path)[source]

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

Parameters:

directory (str | Path) – Directory to read input files from.

run(path: str | Path, timeout=30)[source]

Run packmol and write out the packed structure.

Parameters:
  • path – The path in which packmol input files are located.

  • timeout – Timeout in seconds.

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

  • TimeoutExpiredError if packmold does not finish within the timeout.

pymatgen.io.phonopy module

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

eigvec_to_eigdispl(v, 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]

Creates 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]

Creates 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]

Creates 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]

Creates 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)[source]

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

get_ph_dos(total_dos_path)[source]

Creates 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, supercell_matrix: ndarray, force_constants: 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, supercell_matrix: ndarray, force_constants: 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, supercell_matrix: ndarray, force_constants: 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)[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]

Function to read “thermal_displacement_matrices.yaml” from phonopy and return a list of ThermalDisplacementMatrices objects :param thermal_displacements_yaml: path to thermal_displacement_matrices.yaml :param structure_path: path to POSCAR.

Returns:

pymatgen.io.prismatic module

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

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

Bases: object

Class to write Prismatic (http://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))[source]

Bases: object

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

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

as_dict()[source]

Create a dictionary representation of a PWInput object.

Returns:

dict

classmethod from_dict(pwinput_dict)[source]

Load a PWInput object from a dictionary.

Parameters:

pwinput_dict (dict) – dictionary with PWInput data

Returns:

PWInput object

classmethod from_file(filename)[source]

Reads an PWInput object from a file.

Parameters:

filename (str) – Filename for file

Returns:

PWInput object

classmethod from_str(string)[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[source]

Final energy.

Type:

Returns

get_celldm(idx: int)[source]
Parameters:

idx (int) – index.

Returns:

Cell dimension along index

property lattice_type[source]

Lattice type.

Type:

Returns

patterns = {'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]

Get this res file as a ComputedStructureEntry.

classmethod from_file(filename: str, parse_rems: Literal['gentle', 'strict'] = 'gentle') AirssProvider[source]

Construct a Provider from a file.

classmethod from_str(string: str, parse_rems: Literal['gentle', 'strict'] = 'gentle') AirssProvider[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:

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

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)

get_mpgrid_offset_nkpts_spacing() tuple[tuple[int, int, int], Vector3D, 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)

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: 'Vector3D', occupancy: 'float', spin: 'float | None')[source]

Bases: object

occupancy: float[source]
pos: Vector3D[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

Class providing 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, filename: str) None[source]

Write a pymatgen Structure to a res file.

classmethod structure_to_str(structure: Structure) 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

Provides access to elements of the res file in the form of familiar pymatgen objects.

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

classmethod from_file(filename: str) ResProvider[source]

Construct a Provider from a file.

classmethod from_str(string: str) ResProvider[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: 'set[str]', ions: 'list[Ion]')[source]

Bases: object

ions: list[Ion][source]
species: set[str][source]
class ResWriter(entry: Structure | 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

Class for reading, updating, and writing 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]

Returns: 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)[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)[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, reciprocal_density: int | None = 50000, **kwargs)[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')[source]

Writes 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: str | Path, variables: dict | None = None, filename: str = 'input.txt')[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 – name of 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 for 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]

Boolean that specifies 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 for 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) object[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)[source]

Bases: object

Class for parsing XCrysden files.

Parameters:

structure (Structure) – Structure object.

classmethod from_str(input_string, cls_=None)[source]

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

Parameters:
to_str(atom_symbol=True)[source]

Returns 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

Basic object for working with xr files.

Parameters:

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

classmethod from_file(filename, use_cores=True, thresh=0.0001)[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, use_cores=True, thresh=0.0001)[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)[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]

Returns all the frames of molecule associated with this XYZ.

as_dataframe()[source]

Generates 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) XYZ[source]

Creates XYZ object from a file.

Parameters:

filename – XYZ filename

Returns:

XYZ object

classmethod from_str(contents) XYZ[source]

Creates XYZ object from a string.

Parameters:

contents – String representing an XYZ file.

Returns:

XYZ object

property molecule: Molecule[source]

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

write_file(filename: str) None[source]

Writes XYZ to 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 http://zeoplusplus.org. Instructions can be found at http://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)[source]

Reads a CSSR file to a ZeoCssr object.

Parameters:

filename – Filename to read from.

Returns:

ZeoCssr object.

classmethod from_str(string)[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

Class to 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)[source]

Creates XYZ object from a file.

Parameters:

filename – XYZ filename

Returns:

XYZ object

classmethod from_str(contents)[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++ f