tessl/pypi-pymatgen
Comprehensive materials science analysis library for crystal structures, molecules, and materials data with extensive computational chemistry integration.
—
Pending
electronic-structure.mddocs/
Electronic Structure Analysis
Band structure analysis, density of states processing, transport properties calculation via BoltzTraP, and COHP analysis for chemical bonding insights. These tools enable comprehensive analysis of electronic properties from DFT calculations and provide visualization and interpretation capabilities for materials science research.
Capabilities
Band Structure Analysis
Classes for representing, analyzing, and plotting electronic band structures from DFT calculations.
class BandStructure:
"""
Generic band structure representation with k-points and eigenvalues.
Parameters:
- kpoints: List of Kpoint objects or k-point coordinates
- eigenvals: Dict of eigenvalues {Spin: array of eigenvalues}
- lattice: Lattice object for reciprocal space
- efermi: Fermi energy in eV
- labels_dict: Dict of k-point labels {string: kpoint}
- coords_are_cartesian: Whether k-point coords are Cartesian
- structure: Associated Structure object
- projections: Orbital projections data
"""
def __init__(self, kpoints, eigenvals, lattice, efermi, labels_dict=None,
coords_are_cartesian=False, structure=None, projections=None): ...
def get_band_gap(self):
"""
Get band gap information.
Returns:
dict: Band gap data with energy, direct/indirect, and k-points
"""
def get_cbm(self):
"""
Get conduction band minimum information.
Returns:
dict: CBM energy, k-point, and band index
"""
def get_vbm(self):
"""
Get valence band maximum information.
Returns:
dict: VBM energy, k-point, and band index
"""
def get_direct_band_gap_dict(self):
"""
Get direct band gaps at all k-points.
Returns:
dict: Direct band gaps by k-point
"""
def get_direct_band_gap(self):
"""
Get minimum direct band gap.
Returns:
float: Direct band gap energy in eV
"""
def is_metal(self, efermi_tol=1e-4):
"""
Check if material is metallic.
Parameters:
efermi_tol: Tolerance for Fermi energy crossing bands
Returns:
bool: True if metallic
"""
@property
def nb_bands(self):
"""Number of bands."""
@property
def bands(self):
"""Band eigenvalues as dict {Spin: array}."""
@property
def is_spin_polarized(self):
"""Whether calculation is spin-polarized."""
def get_projection_on_elements(self):
"""
Get orbital projections summed by element.
Returns:
dict: Projections by element
"""
def get_projections_on_elts_and_orbitals(self, el_orb_spec):
"""
Get projections on specific elements and orbitals.
Parameters:
el_orb_spec: Dict specifying elements and orbitals
Returns:
dict: Filtered projections
"""class BandStructureSymmLine:
"""
Band structure along high-symmetry lines with labels.
Inherits all BandStructure methods plus:
"""
def get_equivalent_kpoints(self, index, cartesian=False):
"""
Get equivalent k-points by symmetry.
Parameters:
index: K-point index
cartesian: Whether to return Cartesian coordinates
Returns:
list: Equivalent k-points
"""
def get_branch(self, index):
"""
Get branch containing k-point index.
Parameters:
index: K-point index
Returns:
list: Branch information
"""
@property
def branches(self):
"""List of k-point branches between high-symmetry points."""
def apply_scissor(self, new_band_gap):
"""
Apply scissor correction to band gap.
Parameters:
new_band_gap: Target band gap in eV
Returns:
BandStructureSymmLine: Corrected band structure
"""Density of States Analysis
Classes for analyzing and manipulating electronic density of states data.
class Dos:
"""
Generic density of states spectrum.
Parameters:
- efermi: Fermi energy in eV
- energies: Array of energy values
- densities: Dict of DOS values {Spin: array}
"""
def __init__(self, efermi, energies, densities): ...
def get_interpolated_value(self, energy):
"""
Get interpolated DOS value at given energy.
Parameters:
energy: Energy in eV
Returns:
dict: DOS values by spin
"""
def get_interpolated_gap(self, tol=0.001, abs_tol=False, spin=None):
"""
Get interpolated band gap from DOS.
Parameters:
tol: Tolerance for zero DOS
abs_tol: Whether tolerance is absolute
spin: Specific spin channel
Returns:
tuple: (gap_energy, cbm_vbm_data)
"""
def get_cbm_vbm(self, tol=0.001, abs_tol=False, spin=None):
"""
Get CBM and VBM from DOS.
Returns:
tuple: (cbm_energy, vbm_energy)
"""
def get_gap(self, tol=0.001, spin=None):
"""
Get band gap from DOS.
Returns:
float: Band gap in eV
"""
@property
def energies(self):
"""Energy array."""
@property
def densities(self):
"""DOS densities by spin."""
@property
def efermi(self):
"""Fermi energy."""class CompleteDos:
"""
Complete DOS with atomic and orbital projections.
Parameters:
- structure: Associated Structure object
- total_dos: Total DOS object
- pdoss: Dict of projected DOS by site {site_index: {orbital: Dos}}
"""
def __init__(self, structure, total_dos, pdoss): ...
def get_element_dos(self):
"""
Get DOS projected by element.
Returns:
dict: DOS by element type
"""
def get_spd_dos(self):
"""
Get DOS projected by s, p, d orbitals.
Returns:
dict: DOS by orbital type (s, p, d)
"""
def get_element_spd_dos(self, el):
"""
Get element-specific orbital-projected DOS.
Parameters:
el: Element symbol or Element object
Returns:
dict: DOS by orbital for the element
"""
def get_site_dos(self, site):
"""
Get DOS for a specific site.
Parameters:
site: Site object or site index
Returns:
Dos: DOS for the site
"""
def get_site_orbital_dos(self, site, orbital):
"""
Get orbital-specific DOS for a site.
Parameters:
site: Site object or site index
orbital: Orbital (e.g., Orbital.s, Orbital.px)
Returns:
Dos: Orbital-projected DOS
"""
def get_site_spd_dos(self, site):
"""
Get s, p, d projected DOS for a site.
Parameters:
site: Site object or site index
Returns:
dict: DOS by orbital type for the site
"""
def get_site_t2g_eg_resolved_dos(self, site):
"""
Get t2g and eg resolved DOS for a site.
Parameters:
site: Site object or site index
Returns:
dict: DOS by t2g and eg orbitals
"""
@property
def structure(self):
"""Associated structure."""
@property
def pdos(self):
"""Projected DOS dictionary."""Orbital Analysis
Classes for representing electronic orbitals and magnetic moments.
class Orbital:
"""
Electronic orbital enumeration.
Available orbitals:
- s
- py, pz, px
- dxy, dyz, dz2, dxz, dx2
- f_3, f_2, f_1, f0, f1, f2, f3
"""
@staticmethod
def orbital_type(self):
"""
Get orbital type (s, p, d, f).
Returns:
OrbitalType: Type of orbital
"""
class Spin:
"""
Spin enumeration (up = 1, down = -1).
"""
up = 1
down = -1
class Magmom:
"""
Magnetic moment representation with Cartesian components.
Parameters:
- moment: Magnetic moment (float for collinear, list for non-collinear)
- saxis: Spin axis for non-collinear magnetism
"""
def __init__(self, moment, saxis=(0, 0, 1)): ...
@property
def x(self): ...
@property
def y(self): ...
@property
def z(self): ...
def get_moment(self, saxis=(0, 0, 1)):
"""
Get magnetic moment along specified axis.
Parameters:
saxis: Spin axis direction
Returns:
float: Magnetic moment component
"""
def get_xyz_magmom_with_saxis(self, saxis):
"""
Get Cartesian magnetic moment components with spin axis.
Returns:
numpy.ndarray: [x, y, z] moment components
"""
@property
def global_moment(self):
"""Global magnetic moment magnitude."""
def get_consistent_set_and_saxis(self, magmoms, saxis=None):
"""
Get consistent set of magnetic moments and spin axis.
Parameters:
magmoms: List of magnetic moments
saxis: Preferred spin axis
Returns:
tuple: (consistent_magmoms, spin_axis)
"""Transport Properties (BoltzTraP)
Integration with BoltzTraP for calculating transport properties from band structures.
class BztInterpolator:
"""
BoltzTraP2 interpolation interface for transport properties.
Parameters:
- kpoints: K-point mesh
- energies: Band eigenvalues
- curvature: Curvature data
- bandana: Band analysis data
- cband: Conduction band data
- eband: Energy band data
- proj: Projection data
- mommat: Momentum matrix elements
- magmom: Magnetic moments
"""
def __init__(self, kpoints=None, energies=None, curvature=None,
bandana=None, cband=None, eband=None, proj=None,
mommat=None, magmom=None): ...
@classmethod
def from_files(cls, fildos="DOS", filvol="DOSCAR", filband="EIGENVAL",
filproj="PROCAR", filkp="IBZKPT"):
"""
Create interpolator from files.
Parameters:
fildos, filvol, filband, filproj, filkp: File paths
Returns:
BztInterpolator: Configured interpolator
"""
@classmethod
def from_band_structure(cls, bs, nelect, lpfac=10, run_boltztrap=True,
dos_type="HISTO", energy_grid=None, lpfac_k=None,
curvature=True, save_bztInterp=True,
fname="bztInterp.json.gz", doping=None,
def get_average_eff_mass(self, output="eigs", doping_levels=False):
"""
Get average effective mass.
Parameters:
output: Output format ("eigs" or "tensors")
doping_levels: Whether to calculate for doping levels
Returns:
dict: Effective mass data
"""
def get_seebeck_eff_mass(self, output="eigs", temp_r=None, doping_levels=False):
"""
Get Seebeck effective mass.
Parameters:
output: Output format
temp_r: Temperature range
doping_levels: Whether to calculate for doping levels
Returns:
dict: Seebeck effective mass data
"""
def get_complexity_factor(self, output="eigs", temp_r=300, doping_levels=False,
k_B=8.617e-05):
"""
Get complexity factor for thermoelectric performance.
Returns:
dict: Complexity factor data
"""
def get_carrier_concentration(self):
"""
Get carrier concentration.
Returns:
dict: Carrier concentration by temperature and doping
"""
def get_conductivity(self, output="eigs", relaxation_time=1e-14, doping_levels=False):
"""
Get electrical conductivity.
Parameters:
output: Output format
relaxation_time: Electronic relaxation time in seconds
doping_levels: Whether to calculate for doping levels
Returns:
dict: Conductivity data
"""
def get_seebeck(self, output="eigs", doping_levels=False):
"""
Get Seebeck coefficient.
Returns:
dict: Seebeck coefficient data
"""
def get_thermal_conductivity(self, output="eigs", relaxation_time=1e-14,
beta_const_strain_tensor=None, doping_levels=False,
kl_coeff=1.0):
"""
Get thermal conductivity.
Parameters:
output: Output format
relaxation_time: Electronic relaxation time
beta_const_strain_tensor: Thermal expansion tensor
doping_levels: Whether to calculate for doping levels
kl_coeff: Lattice thermal conductivity coefficient
Returns:
dict: Thermal conductivity data
"""
def get_power_factor(self, output="eigs", relaxation_time=1e-14, doping_levels=False):
"""
Get thermoelectric power factor.
Returns:
dict: Power factor data
"""
def get_zt(self, output="eigs", relaxation_time=1e-14,
beta_const_strain_tensor=None, doping_levels=False, kl_coeff=1.0):
"""
Get thermoelectric figure of merit (ZT).
Returns:
dict: ZT data
"""class BztTransportProperties:
"""
Transport properties calculated by BoltzTraP.
Parameters:
- complete_dos: Complete DOS object
- nelect: Number of electrons
- temperature: Temperature array
- doping: Doping concentration array
- mu_r: Chemical potential array
- seebeck: Seebeck coefficient data
- sigma: Conductivity data
- kappa: Thermal conductivity data
- hall: Hall coefficient data
- structure: Associated structure
"""
def __init__(self, complete_dos, nelect, temperature=None, doping=None,
mu_r=None, seebeck=None, sigma=None, kappa=None,
hall=None, structure=None): ...
def check_acc_bzt_bands(self, args):
"""
Check accuracy of BoltzTraP band interpolation.
Returns:
dict: Accuracy metrics
"""
@property
def doping(self):
"""Doping concentration array."""
@property
def mu_doping(self):
"""Chemical potential vs doping."""
@property
def mu_r(self):
"""Reduced chemical potential array."""
@property
def seebeck_doping(self):
"""Seebeck coefficient vs doping."""
@property
def sigma_doping(self):
"""Conductivity vs doping."""
@property
def kappa_doping(self):
"""Thermal conductivity vs doping."""
@property
def hall_doping(self):
"""Hall coefficient vs doping."""
@property
def power_factor_doping(self):
"""Power factor vs doping."""
@property
def zt_doping(self):
"""ZT vs doping."""
@property
def average_eff_mass_doping(self):
"""Average effective mass vs doping."""
@property
def seebeck_eff_mass_doping(self):
"""Seebeck effective mass vs doping."""COHP Analysis
Crystal Orbital Hamilton Population analysis for chemical bonding insights.
class Cohp:
"""
Crystal Orbital Hamilton Population data.
Parameters:
- efermi: Fermi energy
- energies: Energy array
- cohp: COHP values by spin {Spin: array}
- are_coops: Whether data represents COOP instead of COHP
- icohp: Integrated COHP values by spin
"""
def __init__(self, efermi, energies, cohp, are_coops=False, icohp=None): ...
def get_interpolated_value(self, energy, integrated=False):
"""
Get interpolated COHP value at given energy.
Parameters:
energy: Energy in eV
integrated: Whether to return integrated COHP
Returns:
dict: COHP values by spin
"""
def get_icohp(self, spin=None, integrated=True):
"""
Get integrated COHP up to Fermi level.
Parameters:
spin: Specific spin channel
integrated: Whether to return integrated values
Returns:
dict or float: Integrated COHP values
"""
@property
def energies(self):
"""Energy array."""
@property
def cohp(self):
"""COHP values by spin."""
@property
def icohp(self):
"""Integrated COHP values."""class CompleteCohp:
"""
Complete COHP analysis with bond-resolved data.
Parameters:
- structure: Associated structure
- avg_cohp: Average COHP
- cohp_dict: COHP data by bond label
- bonds: Bond information dictionary
- are_coops: Whether data represents COOP
- orb_res_cohp: Orbital-resolved COHP data
"""
def __init__(self, structure, avg_cohp, cohp_dict, bonds=None,
are_coops=False, orb_res_cohp=None): ...
def get_cohp_by_label(self, label, summed_spin_channels=False):
"""
Get COHP data for a specific bond label.
Parameters:
label: Bond label string
summed_spin_channels: Whether to sum spin channels
Returns:
Cohp: COHP object for the bond
"""
def get_orbital_resolved_cohp(self, label, orbitals, summed_spin_channels=False):
"""
Get orbital-resolved COHP for a bond.
Parameters:
label: Bond label
orbitals: Orbital specification
summed_spin_channels: Whether to sum spin channels
Returns:
Cohp: Orbital-resolved COHP
"""
def get_summed_cohp_by_label_list(self, label_list, divisor=1,
summed_spin_channels=False):
"""
Get summed COHP for multiple bond labels.
Parameters:
label_list: List of bond labels
divisor: Divisor for averaging
summed_spin_channels: Whether to sum spin channels
Returns:
Cohp: Summed COHP object
"""
def get_summed_cohp_by_label_and_orbital_list(self, label_list, orbital_list,
divisor=1, summed_spin_channels=False):
"""
Get summed orbital-resolved COHP.
Parameters:
label_list: List of bond labels
orbital_list: List of orbitals
divisor: Divisor for averaging
summed_spin_channels: Whether to sum spin channels
Returns:
Cohp: Summed orbital-resolved COHP
"""
@property
def bonds(self):
"""Bond information dictionary."""
@property
def all_cohps(self):
"""All COHP data by label."""Plotting and Visualization
Classes for plotting electronic structure data.
class BSPlotter:
"""
Band structure plotting utility.
Parameters:
- bs: BandStructure object to plot
"""
def __init__(self, bs): ...
def get_plot(self, zero_to_efermi=True, ylim=None, smooth=False,
vbm_cbm_marker=False, smooth_tol=None, smooth_k=None,
bs_labels=None, plot_negative=None):
"""
Get matplotlib plot object for band structure.
Parameters:
zero_to_efermi: Whether to set Fermi level to zero
ylim: Y-axis limits
smooth: Whether to smooth bands
vbm_cbm_marker: Whether to mark VBM/CBM
smooth_tol: Smoothing tolerance
smooth_k: Smoothing parameter
bs_labels: Custom band labels
plot_negative: Whether to plot negative eigenvalues
Returns:
matplotlib.pyplot: Plot object
"""
def show(self, zero_to_efermi=True, ylim=None, smooth=False,
vbm_cbm_marker=False, smooth_tol=None, smooth_k=None):
"""
Show band structure plot.
"""
def save_plot(self, filename, img_format="eps", **kwargs):
"""
Save band structure plot to file.
Parameters:
filename: Output filename
img_format: Image format (eps, png, pdf, etc.)
"""
def get_ticks(self):
"""
Get k-point ticks for plotting.
Returns:
dict: K-point labels and positions
"""class DosPlotter:
"""
Density of states plotting utility.
Parameters:
- zero_at_efermi: Whether to set Fermi level to zero
- stack: Whether to stack DOS plots
"""
def __init__(self, zero_at_efermi=True, stack=False): ...
def add_dos(self, label, dos):
"""
Add DOS to plotter.
Parameters:
label: Label for the DOS
dos: Dos object
"""
def add_dos_dict(self, dos_dict, key_sort_func=None):
"""
Add dictionary of DOS objects.
Parameters:
dos_dict: Dictionary of {label: Dos}
key_sort_func: Function for sorting keys
"""
def get_plot(self, xlim=None, ylim=None, invert_axes=False,
beta_dashed=False, sigma=None):
"""
Get matplotlib plot for DOS.
Parameters:
xlim: X-axis limits
ylim: Y-axis limits
invert_axes: Whether to invert x and y axes
beta_dashed: Whether to use dashed lines for spin-down
sigma: Gaussian broadening parameter
Returns:
matplotlib.pyplot: Plot object
"""
def show(self, xlim=None, ylim=None, **kwargs):
"""Show DOS plot."""
def save_plot(self, filename, img_format="eps", xlim=None, ylim=None, **kwargs):
"""Save DOS plot to file."""class CohpPlotter:
"""
COHP plotting utility.
Parameters:
- zero_at_efermi: Whether to set Fermi level to zero
- are_coops: Whether data represents COOP
"""
def __init__(self, zero_at_efermi=True, are_coops=False): ...
def add_cohp(self, label, cohp):
"""
Add COHP to plotter.
Parameters:
label: Label for COHP
cohp: Cohp object
"""
def add_cohp_dict(self, cohp_dict, key_sort_func=None):
"""
Add dictionary of COHP objects.
Parameters:
cohp_dict: Dictionary of {label: Cohp}
key_sort_func: Function for sorting keys
"""
def get_plot(self, xlim=None, ylim=None, plot_negative=None,
integrated=False, invert_axes=False, sigma=None):
"""
Get matplotlib plot for COHP.
Parameters:
xlim: X-axis limits
ylim: Y-axis limits
plot_negative: Whether to plot negative COHP
integrated: Whether to plot integrated COHP
invert_axes: Whether to invert axes
sigma: Gaussian broadening
Returns:
matplotlib.pyplot: Plot object
"""
def show(self, xlim=None, ylim=None, **kwargs):
"""Show COHP plot."""
def save_plot(self, filename, img_format="eps", **kwargs):
"""Save COHP plot to file."""Install with Tessl CLI
npx tessl i tessl/pypi-pymatgen