schrodinger.application.matsci.espresso.qeoutput module

Classes and functions to deal reading XML generated by Quantum Espresso.

Copyright Schrodinger, LLC. All rights reserved.

class schrodinger.application.matsci.espresso.qeoutput.KptLegend(label, coords)

Bases: tuple

__contains__(key, /)

Return key in self.

__len__()

Return len(self).

coords

Alias for field number 1

count(value, /)

Return number of occurrences of value.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

label

Alias for field number 0

class schrodinger.application.matsci.espresso.qeoutput.WfcType(atom_idx, atom_type, n_qn, l_qn, m_qn)

Bases: tuple

__contains__(key, /)

Return key in self.

__len__()

Return len(self).

atom_idx

Alias for field number 0

atom_type

Alias for field number 1

count(value, /)

Return number of occurrences of value.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

l_qn

Alias for field number 3

m_qn

Alias for field number 4

n_qn

Alias for field number 2

class schrodinger.application.matsci.espresso.qeoutput.EsmType(data, bc_type, efield)

Bases: tuple

__contains__(key, /)

Return key in self.

__len__()

Return len(self).

bc_type

Alias for field number 1

count(value, /)

Return number of occurrences of value.

data

Alias for field number 0

efield

Alias for field number 2

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

schrodinger.application.matsci.espresso.qeoutput.gaussian_delta(eigenval, energies, degauss)

Get Gaussian-function values

Parameters
  • eigenval (float) – Energy at which to calculate Gaussian delta

  • energies (numpy.array) – Energy grid

  • degauss (float) – Broadening

Return type

numpy.array

Returns

delta values on the grid

class schrodinger.application.matsci.espresso.qeoutput.KPoint(tag, vecs=None)

Bases: object

Class to hold information about a k-point.

__init__(tag, vecs=None)

Initialize KPoint object from ElementTree element.

Parameters
  • tag (xml.etree.ElementTree.Element) – k_point tag

  • vecs (numpy array (3x3)) – Cell vectors

getCoords(coords_str)

Return list of coordinates.

Parameters

coords_str (str) – String representing K-point coordinates

Return type

list of three floats

Returns

K-point coordinates

getCoordsStr(frac=False)

Get string representation of the coordinates.

Parameters

frac (bool) – If True, self.frac_coords are returned, otherwise self.cart_coords

Return type

str

Returns

String representation of the coordinates

static getKptFromCfg(kpt)
class schrodinger.application.matsci.espresso.qeoutput.DOS(band, dos_fn)

Bases: object

Basic DOS class, based on the class from pymatgen (MIT license).

__init__(band, dos_fn)

Initialize DOS object. ‘band’ can be None, in this case, dos_fn MUST point to the .dos file. If both ‘band’ and ‘dos_fn’ are present, former one has priority.

Parameters
  • band (BandStructure) – BandStructure object to extract eigenvalues and k-points from

  • dos_fn (str) – .dos filename. This file holds DOS plot data

canBroaden()

Can getDOS (broadening) be called on this object.

Return type

bool

Returns

True if it can, otherwise False

getDOS(degauss, delta_e=0.01)

Broaden energies and set DOS in self.dos. This requires self.band to be set in the constructor. Saves degauss in self.degauss.

Parameters
  • degauss (float) – Used only if dos is True, broadening (eV) for computing DOS

  • delta_e (float) – Used only if dos is True, energy grid spacing (in eV)

Raises

ValueError – If self.band is None

getDensities(spin=None)

Get density of states for a particular spin.

Parameters

spin (str or None) – Can be SPIN_UP or SPIN_DW or None.

Return type

numpy.array

Returns

Density of states for a particular spin. If Spin is None, the sum of all spins is returned.

getCbmVbm(tol=0.001, abs_tol=False, spin=None)

Get Conduction Band Minimum (cbm) and Valence Band Maximum (vbm).

Param

tolerance in occupations for determining the cbm/vbm

Parameters
  • abs_tol (bool) – An absolute tolerance (True) or a relative one (False)

  • spin (str or None) – Possible values are None - finds the cbm/vbm in the summed densities, SPIN_UP - finds the cbm/vbm in the up spin channel, SPIN_DW - finds the cbm/vbm in the down spin channel.

Return type

float, float

Returns

cbm and vbm in Ry corresponding to the gap

getGap(tol=0.001, abs_tol=False, spin=None)

Get the gap.

Param

tolerance in occupations for determining the gap

Parameters
  • abs_tol (bool) – An absolute tolerance (True) or a relative one (False)

  • spin (str or None) – Possible values are None - finds the gap in the summed densities, SPIN_UP - finds the gap in the up spin channel, SPIN_DW - finds the gap in the down spin channel.

Return type

float

Returns

gap in Ry or 0.0, if it is a metal

class schrodinger.application.matsci.espresso.qeoutput.PhDOS(freqs, densities=None, min_pos_freq=0.001)

Bases: object

Phonon DOS class.

DOS_FREQ_GRID_SPACING = 1.0
DOS_FREQ_DEGAUSS = 10.0
MIN_POS_FREQ = 0.001
__init__(freqs, densities=None, min_pos_freq=0.001)

Initialize PhDOS object.

Parameters
  • freqs (list[float]) – Frequencies, in 1/cm

  • densities (list[float]) – Densities

  • min_pos_freq (float) – Minimum value of a frequency (cm-1), to be considered positive

property has_densities

Check whether self.densities are present.

Return type

bool

Returns

Whether self.densities are present

classmethod fromPHDOS(file_fh)

Initialize PhDOS object from a .phdos file handler.

Parameters

file_fh (file) – File handler of phonon DOS from matdyn.x

Return type

PhDOS

Returns

New PhDOS object

classmethod fromSPM(spm_obj)

Initialize PhDOS object from a SPM file name / handler.

Parameters

spm_obj (str or file handler) – SPM file name or handler. If handler, it should have been opened in the rb mode

Return type

PhDOS

Returns

New PhDOS object

c_v(temperature)

Constant volume specific heat C_v at temperature T obtained from the integration of the DOS. Only positive frequencies will be used. Result in J/(K*mol-c). A mol-c is the abbreviation of a mole-cell, that is, the number of Avogadro times the atoms in a unit cell. To compare with experimental data the result should be divided by the number of unit formulas in the cell. If the structure is provided the division is performed internally and the result is in J/(K*mol).

Parameters

temperature (float) – Temperature at which to evaluate C_v, in K

Return type

float

Returns

Constant volume specific heat C_v in J/(K*mol)

entropy(temperature)

Vibrational entropy at temperature T obtained from the integration of the DOS. Only positive frequencies will be used. Result in J/(K*mol-c). A mol-c is the abbreviation of a mole-cell, that is, the number of Avogadro times the atoms in a unit cell. To compare with experimental data the result should be divided by the number of unit formulas in the cell. If the structure is provided the division is performed internally and the result is in J/(K*mol).

Parameters

temperature (float) – Temperature at which to evaluate C_v, in K

Return type

float

Returns

Vibrational entropy in J/(K*mol)

internal_energy(temperature)

Phonon contribution to the internal energy at temperature T obtained from the integration of the DOS. Only positive frequencies will be used. Result in J/mol-c. A mol-c is the abbreviation of a mole-cell, that is, the number of Avogadro times the atoms in a unit cell. To compare with experimental data the result should be divided by the number of unit formulas in the cell. If the structure is provided the division is performed internally and the result is in J/mol.

Parameters

temperature (float) – Temperature at which to evaluate energy, in K

Return type

float

Returns

Phonon contribution to the internal energy, in J/mol.

helmholtz_free_energy(temperature)

Phonon contribution to the Helmholtz free energy at temperature T obtained from the integration of the DOS. Only positive frequencies will be used. Result in J/mol-c. A mol-c is the abbreviation of a mole-cell, that is, the number of Avogadro times the atoms in a unit cell. To compare with experimental data the result should be divided by the number of unit formulas in the cell. If the structure is provided the division is performed internally and the result is in J/mol.

Parameters

temperature (float) – Temperature at which to evaluate free energy, in K

Return type

float

Returns

Phonon contribution to the Helmholtz free energy, in J/mol

zero_point_energy()

Zero point energy energy of the system. Only positive frequencies will be used. Result in J/mol-c. A mol-c is the abbreviation of a mole-cell, that is, the number of Avogadro times the atoms in a unit cell. To compare with experimental data the result should be divided by the number of unit formulas in the cell. If the structure is provided the division is performed internally and the result is in J/mol.

Parameters

temperature (float) – Temperature at which to evaluate ZPE, in K

Return type

float

Returns

Phonon contribution to ZPE, in J/mol

getDOS(degauss=10.0, delta_e=1.0)

Broaden energies and set DOS in self.dos. This requires self.band to be set in the constructor. Saves degauss in self.degauss.

Parameters
  • degauss (float) – Broadening (cm-1)

  • delta_e (float) – Energy grid spacing (cm-1)

Return type

numpy.array[float], numpy.array[float]

Returns

Frequencies and corresponding DOS

class schrodinger.application.matsci.espresso.qeoutput.PDOS(proj, wfc_types, efermi, band)

Bases: object

Class that holds partial DOS (PDOS) data. Call getPDOS to get broadened data.

NUM_IDX = 5
LDOS_IDX = 0
ADOS_IDX = 1
EDOS_IDX = 2
AIDOS_IDX = 3
ALDOS_IDX = 4
__init__(proj, wfc_types, efermi, band)

Initialize PDOS object. Constructor only assigns values, call getPDOS for broadening.

Parameters
  • proj (dict of 3d numpy.array) – Dict with SPIN_UP, SPIN_DW (optional) keys, each containing a 3D array containing: index of projected atom wavefunction, index of k-point, index of band and WFC projection as value.

  • wfc_types (list of WfcType) – List containing wavefunction types description

  • efermi (float) – Fermi energy in eV

getPDOS(degauss, delta_e=0.01)

Calculate PDOS and set in self.pdos. Saves degauss in self.degauss.

Parameters
  • degauss (float) – Broadening (eV) for computing PDOS

  • delta_e (float) – Energy grid spacing eV

class schrodinger.application.matsci.espresso.qeoutput.BandStructure(kpoints, eigenvals, efermi, struct=None)

Bases: object

This class is based on the class from pymatgen (MIT license).

__init__(kpoints, eigenvals, efermi, struct=None)

Initialize BandStructure object.

Param

List of k-points for this band structure

Parameters

eigenvals (dict) –

Energies of the band structure in the shape:

{SPIN_UP: numpy.array([iband, jkpoint]),              SPIN_DW: numpy.array([iband, jkpoint])}

SPIN_DW key can be present or not depending on the calculation type

Parameters
  • efermi (float) – Fermi energy in Hartree

  • struct (structure.Structure) – Related structure

isMetal()

Check if the band structure indicates a metal by looking if the Fermi level crosses a band.

Return type

bool

Returns

True, if the system is metallic

getVbmCbm(vbm=True)

Return data about the valence band maximum (VBM) or conduction band minimum (CBM).

Parameters

vbm (bool) – If True calculates VBM, if False CBM

Return type

dict

Returns

dict with keys BAND_INDEX_KEY, KPOINT_INDEX_KEY, KPOINT_KEY, ENERGY_KEY where: - BAND_INDEX_KEY: A dict with spin keys pointing to a list of the indices of the band containing the VBM (please note that you can have several bands sharing the VBM) {SPIN_UP:[], SPIN_DW:[]} - KPOINT_INDEX_KEY: The list of indices in self.kpoints for the kpoint vbm. Please note that there can be several kpoint_indices relating to the same kpoint (e.g., Gamma can occur at different spots in the band structure line plot) - KPOINT_KEY: The kpoint (as a kpoint object) - ENERGY_KEY: The energy of the VBM

getBandGap()

Get band gap data.

Return type

dict

Returns

dict with keys ENERGY_KEY, DIRECT_KEY, TRANSITION_KEY: ENERGY_KEY: band gap energy DIRECT_KEY: A boolean telling if the gap is direct or not TRANSITION_KEY: kpoint labels of the transition (e.g., “Gamma-X”)

generatePlotData()

Generate distances between k-points (in self.distances) for plotting band structure.

class schrodinger.application.matsci.espresso.qeoutput.Output(qegz_fn, tree=None, dos_fn=None, **kwargs)

Bases: object

Class to deal with QE XML output parsing.

PROPERTIES = ('struct', 'band', 'dos', 'pdos', 'esm', 'neb', 'phdos', 'phband', 'dynamics', 'epsilon', 'hpu', 'nmr')
EPS_METAL_ERR = 'Metallic system encountered in epsilon calculation.'
__init__(qegz_fn, tree=None, dos_fn=None, **kwargs)

Initialize Output object. Supported properties are requested in kwargs and defined in self.PROPERTIES.

Parameters
  • qegz_fn (str) – Archive name of the compressed .save folder

  • tree (ElementTree or None) – Use tree if not None otherwise read tree from the file

  • dos_fn (str or None) – File to read dos property from, will be used if dos=True

classmethod getProperties(**kwargs)

Get properties (namedtuple) from kwargs. Supported properties are defined in self.PROPERTIES.

Return type

namedtuple

Returns

Properties requested

setDOSFromFile(dos_fn)

Parse .dos file and set DOS into self.dos.

Parameters

dos_fn (str) – File to read dos property from

processEpsilonFile(tgz, tgz_file)

Process file from archive, if it is epsilon, return parsed data

Parameters
  • tgz (TarFile) – Tar archive

  • tgz_file (str) – Filename

Return type

dict or None

Returns

Dict with one key (real or imag) and corresponding data in value or None if extensions didn’t match

Raises

ValueError – When numpy can’t parse the data

processFile(tgz, tgz_file, options)

Process file from archive and set object properties.

Parameters
  • tgz (TarFile) – Tar archive

  • tgz_file (str) – Filename

  • options (namedtuple) – Properties to get

getTree(qegz_fn, options)

Get data in from of tree from archived file

Parameters
  • qegz_fn (str) – Archive name

  • options (namedtuple) – Properties to get

Returns

Data from data-file-schema.xml

Return type

xml.etree.ElementTree

getMDStepStruct(root, step, timestep)

Extract MD step structure from step XML.

Parameters
  • root (xml.etree.ElementTree.Element) – Root XML element

  • step (xml.etree.ElementTree.Element) – Step element

  • timestep (float) – MD time step

Return type

structure.Structure, structure.Structure or None

Returns

Structure of the MD step, standardized structure if requested and found

static getFreePositions(root, natom)

Get atom free_positions from the XML data

Parameters
  • root (xml.etree.ElementTree.Element) – Root XML element

  • natom (int) – Number of atoms in the structure

Return type

numpy.array

Returns

Atom free positions

getMaeStructure()

Get structure with lower triangular form of lattice vectors matrix

Return type

structure.Structure

Returns

Updated structure

static parseHP(hp_fh)

Parse and return data from the Hubbard_parameters.dat.

Parameters

hp_fh (File handler object) – Handler of the Hubbard_parameters.dat

Return type

dict

Returns

Dictionary with atom indexes as keys and Hubbard U as values

class schrodinger.application.matsci.espresso.qeoutput.MagresAtom(data)

Bases: object

Class that holds atom NMR properties.

__init__(data)

Initialize object.

Parameters

data (Any) – Data that will be converted to a 3x3 float tensor

Raises

typeError – On Error

property iso

Get isotropic sigma value.

Return type

float

Returns

Isotropic sigma value, ppm

shift(ref=0.0)

Get referenced chemical shift.

Parameters

ref (float) – Reference value.

Return type

float

Returns

Referenced chemical shift

toAtom(atom)

Set sigma to a structure atom (as a property).

Parameters

atom (structure.StructureAtom) – Atom to update

classmethod fromAtom(atom)

Read sigma from structure atom.

Parameters

atom (structure.StructureAtom) – Atom to read from

Return type

bool, MagresAtom or str

Return type

Whether sigma read successfully. If true, return MagresAtom object. If false, return error message

classmethod fromList(data)

Given a list of values, try to initialize MagresAtom object.

Parameters

data (list[Any]) – List of values that are convertible to 3x3 tensor

Return type

bool, MagresAtom or str

Return type

Whether sigma read successfully. If true, return MagresAtom object. If false, return error message

class schrodinger.application.matsci.espresso.qeoutput.Magres(struct, ms_atoms)

Bases: object

Class to hold magres data of a structure.

TAG_RE = re.compile('[\\[<](?P<tag>.*?)[>\\]](.*?)[<\\[]/(?P=tag)[\\]>]', re.MULTILINE|re.DOTALL)
TAGS = ('atoms', 'magres', 'calculation')
class ATTR(value)

Bases: schrodinger.application.matsci.msutils.KeywordEnum

An enumeration.

units = 'units'
lattice = 'lattice'
atom = 'atom'
ms = 'ms'
sus = 'sus'
calc_name = 'calc_name'
calc_code = 'calc_code'
calc_code_version = 'calc_code_version'
UNITS = {ATTR.atom: 'Angstrom', ATTR.lattice: 'Angstrom', ATTR.ms: 'ppm', ATTR.sus: '10^-6.cm^3.mol^-1'}
__init__(struct, ms_atoms)

Initialize object.

Parameters
  • struct (structure.Structure) – Input structure

  • dict[int – MagresAtom]: Dict of magres atoms

static getLineData(text)

Generator that returns split lines.

Parameters

text (str) – (Multi-line) text

Yield list[str]

List from a split line

classmethod fromFile(text)

Create Magres object from text.

Parameters

text (str) – Multiline magres text

Return type

bool, Magres or str

Return type

Whether structure updated successfully. If true, return Magres objectIf false, return an error message

toStructure(struct)

Set magres atom properties to a structure.

Parameters

struct (structure.Structure) – Structure to update

Return type

bool, None or str

Return type

Whether structure updated successfully. If false, return an error message

classmethod fromStructure(struct)

Read magres atoms from structure.

Parameters

struct (structure.Structure) – Structure to read

Return type

bool, Magres or str

Return type

Whether structure updated successfully. If true, return Magres object. If false, return an error message