# coding: utf-8
# Copyright (c) Max-Planck-Institut für Eisenforschung GmbH - Computational Materials Design (CM) Department
# Distributed under the terms of "New BSD License", see the LICENSE file.
from __future__ import print_function
import numpy as np
from pyiron.atomistics.structure.atoms import Atoms
from pyiron.dft.waves.dos import Dos
__author__ = "Sudarsan Surendralal"
__copyright__ = (
"Copyright 2020, Max-Planck-Institut für Eisenforschung GmbH "
"- Computational Materials Design (CM) Department"
)
__version__ = "1.0"
__maintainer__ = "Sudarsan Surendralal"
__email__ = "surendralal@mpie.de"
__status__ = "development"
__date__ = "Sep 1, 2017"
[docs]class ElectronicStructure(object):
"""
This is a generic module to store electronic structure data in a clean way. Kpoint and Band classes are used to
store information related to kpoints and bands respectively. Every spin configuration has a set of k-points and
every k-point has a set of bands associated with it. This is loosely adapted from the `pymatgen electronic_structure
modules`_. Many of the functions have been substantially modified for pyiron
.. _pymatgen electronic_structure modules: http://pymatgen.org/pymatgen.electronic_structure.bandstructure.html
"""
def __init__(self):
self.kpoints = list()
self._eigenvalues = list()
self._occupancies = list()
self._dos_energies = list()
self._dos_densities = list()
self._dos_idensities = list()
self._eg = None
self._vbm = None
self._cbm = None
self._efermi = None
self._eigenvalue_matrix = None
self._occupancy_matrix = None
self._grand_dos_matrix = None
self._resolved_densities = None
self._kpoint_list = list()
self._kpoint_weights = list()
self.n_spins = 1
self._structure = None
self._orbital_dict = None
[docs] def add_kpoint(self, value, weight):
"""
Appends a Kpoint() instance to the kpoints attribute
Args:
value (list/numpy.ndarray): Value of the k-point in cartesian reciprocal coordinates
weight (float): The weight of the particular k-point
"""
kpt_obj = Kpoint()
kpt_obj.value = value
kpt_obj.weight = weight
self.kpoints.append(kpt_obj)
[docs] def get_dos(self, n_bins=100):
"""
Gives a pyiron.objects.waves.dos.Dos instance
Args:
n_bins (int): Number of histogram bins for the dos
Returns:
pyiron.objects.waves.dos.Dos: Dos instance
"""
dos_obj = Dos(n_bins=n_bins, es_obj=self)
return dos_obj
@property
def dos_energies(self):
"""
numpy.ndarray: A (1xN) vector containing the energies with N grid points
"""
return self._dos_energies
@dos_energies.setter
def dos_energies(self, val):
self._dos_energies = val
@property
def dos_densities(self):
"""
numpy.ndarray: A (SxN) vector containing the density of states for every spin configuration with S spin
configurations and N grid points
"""
return self._dos_densities
@dos_densities.setter
def dos_densities(self, val):
self._dos_densities = val
@property
def dos_idensities(self):
"""
numpy.ndarray: A (SxN) vector containing the density of states for every spin configuration with S spin
configurations and N grid points
"""
return self._dos_idensities
@dos_idensities.setter
def dos_idensities(self, val):
self._dos_idensities = val
@property
def resolved_densities(self):
"""
numpy.ndarray: A (SxAxOxN) vector containing the density of states for every spin configuration with S spin
configurations, A atoms, O orbitals and N grid points. The labels of the orbitals are found on
the orbital_dict
"""
return self._resolved_densities
@resolved_densities.setter
def resolved_densities(self, val):
self._resolved_densities = val
@property
def orbital_dict(self):
"""
dict: A dictionary of the ordering of the orbitals
Examples:
>>> self.orbital_dict[0]
's'
"""
return self._orbital_dict
@orbital_dict.setter
def orbital_dict(self, val):
self._orbital_dict = val
@property
def eigenvalues(self):
"""
numpy.ndarray: Eigenvalues of the bands
"""
return self.eigenvalue_matrix.reshape(-1)
@property
def occupancies(self):
"""
numpy.ndarray: Occupancies of the bands
"""
return self.occupancy_matrix.reshape(-1)
@property
def eigenvalue_matrix(self):
"""
numpy.ndarray: A getter function to return the eigenvalue_matrix. The eigenvalue for a given kpoint index i and
band index j is given by eigenvalue_matrix[i][j]
"""
if self._eigenvalue_matrix is None and len(self.kpoints) > 0:
self._eigenvalue_matrix = np.zeros(
(len(self.kpoints), len(self.kpoints[0].bands))
)
for i, k in enumerate(self.kpoints):
self._eigenvalue_matrix[i, :] = k.eig_occ_matrix[:, 0]
return self._eigenvalue_matrix
@eigenvalue_matrix.setter
def eigenvalue_matrix(self, val):
self._eigenvalue_matrix = val
@property
def occupancy_matrix(self):
"""
numpy.ndarray: A getter function to return the occupancy_matrix. The occupancy for a given kpoint index i and
band index j is given by occupancy_matrix[i][j]
"""
if self._occupancy_matrix is None and len(self.kpoints) > 0:
self._occupancy_matrix = np.zeros(
(len(self.kpoints), len(self.kpoints[0].bands))
)
for i, k in enumerate(self.kpoints):
self._occupancy_matrix[i, :] = k.eig_occ_matrix[:, 1]
return self._occupancy_matrix
@occupancy_matrix.setter
def occupancy_matrix(self, val):
self._occupancy_matrix = val
@property
def kpoint_list(self):
"""
list: The list of kpoints in cartesian coordinates
"""
if len(self._kpoint_list) == 0:
kpt_lst = list()
for k in self.kpoints:
kpt_lst.append(k.value)
self._kpoint_list = kpt_lst
return self._kpoint_list
@kpoint_list.setter
def kpoint_list(self, val):
self._kpoint_list = val
@property
def kpoint_weights(self):
"""
list: The weights of the kpoints of the electronic structure in cartesian coordinates
"""
if len(self._kpoint_weights) == 0:
kpt_lst = list()
for k in self.kpoints:
kpt_lst.append(k.weight)
self._kpoint_weights = kpt_lst
return self._kpoint_weights
@kpoint_weights.setter
def kpoint_weights(self, val):
self._kpoint_weights = val
@property
def structure(self):
"""
atomistics.structure.atoms.Atoms: The structure associated with the electronic structure object
"""
return self._structure
@structure.setter
def structure(self, val):
self._structure = val
[docs] def get_vbm(self, resolution=1e-6):
"""
Gets the valence band maximum (VBM) of the system
Args:
resolution (float): An occupancy below this value is considered unoccupied
Returns:
dict:
"value" (float): Absolute energy value of the VBM (eV)
"kpoint": The Kpoint instance associated with the VBM
"band": The Band instance associated with the VBM
"""
vbm = None
vbm_dict = dict()
for kpt in self.kpoints:
for band in kpt.bands:
if band.occupancy > resolution:
if vbm is None:
vbm = band.eigenvalue
vbm_dict["value"] = vbm
vbm_dict["kpoint"] = kpt
vbm_dict["band"] = band
else:
if band.eigenvalue > vbm:
vbm = band.eigenvalue
vbm_dict["value"] = vbm
vbm_dict["kpoint"] = kpt
vbm_dict["band"] = band
return vbm_dict
[docs] def get_cbm(self, resolution=1e-6):
"""
Gets the conduction band minimum (CBM) of the system
Args:
resolution (float): An occupancy above this value is considered occupied
Returns:
dict:
"value" (float): Absolute energy value of the CBM (eV)
"kpoint": The Kpoint instance associated with the CBM
"band": The Band instance associated with the CBM
"""
cbm = None
cbm_dict = dict()
for kpt in self.kpoints:
for band in kpt.bands:
if band.occupancy <= resolution:
if cbm is None:
cbm = band.eigenvalue
cbm_dict["value"] = cbm
cbm_dict["kpoint"] = kpt
cbm_dict["band"] = band
else:
if band.eigenvalue < cbm:
cbm = band.eigenvalue
cbm_dict["value"] = cbm
cbm_dict["kpoint"] = kpt
cbm_dict["band"] = band
return cbm_dict
[docs] def get_band_gap(self, resolution=1e-6):
"""
Gets the band gap of the system
Args:
resolution (float): An occupancy above this value is considered occupied
Returns:
dict:
"band gap" (float): The band gap (eV)
"vbm": The dictionary associated with the VBM
"cbm": The dictionary associated with the CBM
"""
gap_dict = {}
vbm_dict = self.get_vbm(resolution)
cbm_dict = self.get_cbm(resolution)
vbm = vbm_dict["value"]
cbm = cbm_dict["value"]
gap_dict["band_gap"] = max(0.0, cbm - vbm)
gap_dict["vbm"] = vbm_dict
gap_dict["cbm"] = cbm_dict
return gap_dict
@property
def eg(self):
"""
float: The band gap (eV)
"""
self._eg = self.get_band_gap()["band_gap"]
return self._eg
@eg.setter
def eg(self, val):
self._eg = val
@property
def vbm(self):
"""
float: The Kohn-Sham VBM (value only) (eV)
"""
self._vbm = self.get_vbm()["value"]
return self._vbm
@vbm.setter
def vbm(self, val):
self._vbm = val
@property
def cbm(self):
"""
float: The Kohn-Sham CBM (value only) (eV)
"""
self._cbm = self.get_cbm()["value"]
return self._cbm
@cbm.setter
def cbm(self, val):
self._cbm = val
@property
def efermi(self):
"""
float: The Fermi-level of the system (eV). Please note that in the case of DFT this level is the Kohn-Sham Fermi
level computed by the DFT code.
"""
return self._efermi
@efermi.setter
def efermi(self, val):
self._efermi = val
@property
def is_metal(self):
"""
bool: Tells if the given system is metallic or not. The Fermi level crosses bands in the cas of metals but is
present in the band gap in the case of semi-conductors.
"""
if not (self._efermi is not None):
raise ValueError(
"e_fermi has to be set before you can determine if the system is metallic or not"
)
fermi_crossed = False
_, n_bands = np.shape(self.eigenvalue_matrix)
for i in range(n_bands):
values = self.eigenvalue_matrix[:, i]
if (self.efermi < np.max(values)) and (self.efermi >= np.min(values)):
fermi_crossed = True
return fermi_crossed
@property
def grand_dos_matrix(self):
"""
Getter for the 5 dimensional grand_dos_matrix which gives the contribution of every spin, kpoint, band, atom and
orbital to the total DOS. For example the dos contribution with spin index s, kpoint k, band b, atom a and
orbital o is:
grand_dos_matrix[s, k, b, a, o]
The grand sum of this matrix would equal 1.0. The spatial, spin, and orbital resolved DOS can be computed using
this matrix
Returns:
numpy.ndarray (5 dimensional)
"""
if self._grand_dos_matrix is None:
try:
n_atoms, n_orbitals = np.shape(
self.kpoints[0].bands[0].resolved_dos_matrix
)
except ValueError:
return self._grand_dos_matrix
dimension = (
self.n_spins,
len(self.kpoints),
len(self.kpoints[0].bands),
n_atoms,
n_orbitals,
)
self._grand_dos_matrix = np.zeros(dimension)
for spin in range(self.n_spins):
for i, kpt in enumerate(self.kpoints):
for j, band in enumerate(kpt.bands):
self._grand_dos_matrix[
spin, i, j, :, :
] = band.resolved_dos_matrix
return self._grand_dos_matrix
@grand_dos_matrix.setter
def grand_dos_matrix(self, val):
"""
Setter for grand_dos_matrix
"""
self._grand_dos_matrix = val
[docs] def to_hdf(self, hdf, group_name="electronic_structure"):
"""
Store the object to hdf5 file
Args:
hdf: Path to the hdf5 file/group in the file
group_name: Name of the group under which the attributes are o be stored
"""
with hdf.open(group_name) as h_es:
h_es["TYPE"] = str(type(self))
if self.structure is not None:
self.structure.to_hdf(h_es)
h_es["k_points"] = self.kpoint_list
h_es["k_weights"] = self.kpoint_weights
h_es["eig_matrix"] = self.eigenvalue_matrix
h_es["occ_matrix"] = self.occupancy_matrix
if self.efermi is not None:
h_es["efermi"] = self.efermi
with h_es.open("dos") as h_dos:
h_dos["energies"] = self.dos_energies
h_dos["tot_densities"] = self.dos_densities
h_dos["int_densities"] = self.dos_idensities
if self.grand_dos_matrix is not None:
h_dos["grand_dos_matrix"] = self.grand_dos_matrix
if self.resolved_densities is not None:
h_dos["resolved_densities"] = self.resolved_densities
[docs] def from_hdf(self, hdf, group_name="electronic_structure"):
"""
Retrieve the object from the hdf5 file
Args:
hdf: Path to the hdf5 file/group in the file
group_name: Name of the group under which the attributes are stored
"""
if "dos" not in hdf[group_name].list_groups():
self.from_hdf_old(hdf=hdf, group_name=group_name)
else:
with hdf.open(group_name) as h_es:
if "TYPE" not in h_es.list_nodes():
h_es["TYPE"] = str(type(self))
nodes = h_es.list_nodes()
if self.structure is not None:
self.structure.to_hdf(h_es)
self.kpoint_list = h_es["k_points"]
self.kpoint_weights = h_es["k_weights"]
self.eigenvalue_matrix = h_es["eig_matrix"]
self.occupancy_matrix = h_es["occ_matrix"]
if "efermi" in nodes:
self.efermi = h_es["efermi"]
with h_es.open("dos") as h_dos:
nodes = h_dos.list_nodes()
self.dos_energies = h_dos["energies"]
self.dos_densities = h_dos["tot_densities"]
self.dos_idensities = h_dos["int_densities"]
if "grand_dos_matrix" in nodes:
self.grand_dos_matrix = h_dos["grand_dos_matrix"]
if "resolved_densities" in nodes:
self.resolved_densities = h_dos["resolved_densities"]
self.generate_from_matrices()
[docs] def to_hdf_old(self, hdf, group_name="electronic_structure"):
"""
Store the object to hdf5 file
Args:
hdf: Path to the hdf5 file/group in the file
group_name: Name of the group under which the attributes are o be stored
"""
with hdf.open(group_name) as h_es:
h_es["TYPE"] = str(type(self))
if self.structure is not None:
self.structure.to_hdf(h_es)
h_es["k_points"] = self.kpoint_list
h_es["k_point_weights"] = self.kpoint_weights
h_es["eigenvalue_matrix"] = self.eigenvalue_matrix
h_es["occupancy_matrix"] = self.occupancy_matrix
h_es["dos_energies"] = self.dos_energies
h_es["dos_densities"] = self.dos_densities
h_es["dos_idensities"] = self.dos_idensities
if self.efermi is not None:
h_es["fermi_level"] = self.efermi
if self.grand_dos_matrix is not None:
h_es["grand_dos_matrix"] = self.grand_dos_matrix
if self.resolved_densities is not None:
h_es["resolved_densities"] = self.resolved_densities
[docs] def from_hdf_old(self, hdf, group_name="electronic_structure"):
"""
Retrieve the object from the hdf5 file
Args:
hdf: Path to the hdf5 file/group in the file
group_name: Name of the group under which the attributes are stored
"""
with hdf.open(group_name) as h_es:
if "structure" in h_es.list_nodes():
self.structure = Atoms().from_hdf(h_es)
nodes = h_es.list_nodes()
self.kpoint_list = h_es["k_points"]
self.kpoint_weights = h_es["k_point_weights"]
self.eigenvalue_matrix = h_es["eigenvalue_matrix"]
self.occupancy_matrix = h_es["occupancy_matrix"]
try:
self.dos_energies = h_es["dos_energies"]
self.dos_densities = h_es["dos_densities"]
self.dos_idensities = h_es["dos_idensities"]
except ValueError:
pass
if "fermi_level" in nodes:
self.efermi = h_es["fermi_level"]
if "grand_dos_matrix" in nodes:
self.grand_dos_matrix = h_es["grand_dos_matrix"]
if "resolved_densities" in nodes:
self.resolved_densities = h_es["resolved_densities"]
self.generate_from_matrices()
[docs] def generate_from_matrices(self):
"""
Generate the Kpoints and Bands from the kpoint lists and sometimes grand_dos_matrix
"""
for i in range(len(self.kpoint_list)):
self.add_kpoint(self.kpoint_list[i], self.kpoint_weights[i])
_, length = np.shape(self.eigenvalue_matrix)
for j in range(length):
val = self.eigenvalue_matrix[i][j]
occ = self.occupancy_matrix[i][j]
self.kpoints[-1].add_band(eigenvalue=val, occupancy=occ)
if self._grand_dos_matrix is not None:
self.kpoints[-1].bands[
-1
].resolved_dos_matrix = self.grand_dos_matrix[0, i, j, :, :]
[docs] def get_spin_resolved_dos(self, spin_indices=0):
"""
Gets the spin resolved DOS
Args:
spin_indices (int): The index of the spin for which the DOS is required
Returns:
Spin resolved dos (numpy.ndarray instance)
"""
if not (len(self.dos_energies) > 0):
raise ValueError("The DOS is not computed/saved for this vasp run")
return self.dos_densities[spin_indices]
[docs] def get_resolved_dos(self, spin_indices=0, atom_indices=None, orbital_indices=None):
"""
Get resolved dos based on the specified spin, atom and orbital indices
Args:
spin_indices (int/list/numpy.ndarray): spin indices
atom_indices (int/list/numpy.ndarray): stom indices
orbital_indices (int/list/numpy.ndarray): orbital indices (based on orbital_dict)
Returns:
rdos (numpy.ndarray): Required resolved dos
"""
if len(self.dos_energies) == 0:
raise ValueError("The DOS is not computed/saved for this vasp run")
if self.resolved_densities is None:
raise ValueError("The resolved DOS is not available for this calculation")
rdos = None
if isinstance(spin_indices, (list, np.ndarray)):
rdos = np.sum(self.resolved_densities[spin_indices], axis=0)
elif isinstance(spin_indices, int):
rdos = self.resolved_densities[spin_indices]
if atom_indices is not None:
if isinstance(atom_indices, (list, np.ndarray)):
rdos = np.sum(rdos[atom_indices], axis=0)
elif isinstance(atom_indices, int):
rdos = rdos[atom_indices]
else:
rdos = np.sum(rdos, axis=0)
if orbital_indices is not None:
if isinstance(orbital_indices, (list, np.ndarray)):
rdos = np.sum(rdos[orbital_indices], axis=0)
elif isinstance(orbital_indices, int):
rdos = rdos[orbital_indices]
else:
rdos = np.sum(rdos, axis=0)
return rdos
[docs] def plot_fermi_dirac(self):
"""
Plots the obtained eigenvalue vs occupation plot
"""
try:
import matplotlib.pylab as plt
except ModuleNotFoundError:
import matplotlib.pyplot as plt
arg = np.argsort(self.eigenvalues)
plt.plot(
self.eigenvalues[arg], self.occupancies[arg], linewidth=2.0, color="blue"
)
plt.axvline(self.efermi, linewidth=2.0, linestyle="dashed", color="black")
plt.xlabel("Energies (eV)")
plt.ylabel("Occupancy")
return plt
def __del__(self):
del self.kpoints
del self._eigenvalues
del self._occupancies
del self._eg
del self._vbm
del self._cbm
del self._efermi
del self._eigenvalue_matrix
del self._occupancy_matrix
del self._grand_dos_matrix
del self._kpoint_list
del self._kpoint_weights
del self.n_spins
def __str__(self):
output_string = list()
output_string.append("ElectronicStructure Instance")
output_string.append("----------------------------")
if self.grand_dos_matrix is not None:
output_string.append(
"Spin Configurations: {}".format(len(self.grand_dos_matrix))
)
output_string.append("Number of k-points: {}".format(len(self.kpoints)))
output_string.append("Number of bands: {}".format(len(self.kpoints[0].bands)))
try:
if self.is_metal:
output_string.append("Is a metal: {}".format(self.is_metal))
except ValueError:
pass
if not self.is_metal:
output_string.append(
"Band Gap: {} eV".format(self.get_band_gap(resolution=1.0e-4)["band_gap"])
)
return "\n".join(output_string)
def __repr__(self):
return self.__str__()
[docs]class Kpoint(object):
"""
All data related to a single k-point is stored in this module
Attributes:
bands (list): List of pyiron.objects.waves.settings.Band object
.. value (float): Value of the k-point
.. weight (float): Weight of the k-point used in integration of quantities
.. eig_occ_matrix (numpy.ndarray): A Nx2 matrix with the first column with eigenvalues and the second with
occupancies of every band. N being the number of bands assoiated with the k-point
"""
def __init__(self):
self._value = None
self._weight = None
self.bands = list()
self.is_relative = False
@property
def value(self):
return self._value
@value.setter
def value(self, val):
self._value = val
@property
def weight(self):
return self._weight
@weight.setter
def weight(self, val):
self._weight = val
[docs] def add_band(self, eigenvalue, occupancy):
"""
Add a pyiron.objects.waves.core.Band instance
Args:
eigenvalue (float): The eigenvalue associated with the Band instance
occupancy (flaot): The occupancy associated with the Band instance
"""
band_obj = Band()
band_obj.eigenvalue = eigenvalue
band_obj.occupancy = occupancy
self.bands.append(band_obj)
@property
def eig_occ_matrix(self):
return np.array([[b.eigenvalue, b.occupancy] for b in self.bands])
[docs]class Band(object):
"""
All data related to a single band for every k-point is stored in this module
"""
def __init__(self):
self._eigenvalue = None
self._occupancy = None
self._resolved_dos_matrix = None
@property
def eigenvalue(self):
"""
float: The eigenvalue of a given band at a given k-point
"""
return self._eigenvalue
@eigenvalue.setter
def eigenvalue(self, val):
self._eigenvalue = val
@property
def occupancy(self):
"""
float: The occupancy of a given band at a given k-point
"""
return self._occupancy
@occupancy.setter
def occupancy(self, val):
self._occupancy = val
@property
def resolved_dos_matrix(self):
"""
numpy.ndarray instance: 2D matrix with n rows and m columns; n being the unmber of
atoms and m being the number of orbitals
"""
return self._resolved_dos_matrix
@resolved_dos_matrix.setter
def resolved_dos_matrix(self, val):
self._resolved_dos_matrix = val