madman.analysis.edos

  1r"""Electron density of states."""
  2
  3from __future__ import annotations
  4from collections.abc import Mapping, Sequence
  5from itertools import combinations
  6from numbers import Integral, Real
  7
  8import numpy as np
  9from matplotlib import pyplot as plt
 10
 11from madman.analysis.spectrum import (
 12    EnergySpectrumMeta,
 13    EnergySpectrum,
 14    ResolvedEnergySpectrum,
 15)
 16
 17
 18class ElectronDensityOfStatesMeta(EnergySpectrumMeta):
 19    r"""Metaclass of ElectronDensityOfStates."""
 20
 21    @property
 22    def std_axes(cls) -> plt.Axes:
 23        r"""Standard axes to plot electron density of states.
 24
 25        Returns:
 26            Plot axes.
 27        """
 28        _, ax = plt.subplots(tight_layout=True)
 29        ax.set_xlabel(r"Electron energy / $\mathrm{eV}$")
 30        ax.set_ylabel(r"Electron DOS / $\mathrm{eV^{-1}}$")
 31        return ax
 32
 33
 34class ElectronDensityOfStates(
 35    EnergySpectrum, metaclass=ElectronDensityOfStatesMeta
 36):
 37    r"""Electron density of states.
 38
 39    Note:
 40        `energies`: Electron energies [$\mathrm{eV}$].
 41        `values`: Electron density of states values [$\mathrm{eV^{-1}}$].
 42    """
 43
 44    def __init__(
 45        self,
 46        energies: Sequence[Real, ...],
 47        values: Sequence[Real, ...],
 48        *,
 49        d_energy: Real | None = None,
 50    ) -> None:
 51        r"""Initialize ElectronDensityOfStates object.
 52
 53        Args:
 54            energies: Electron energies [$\mathrm{eV}$].
 55            values: Electron density of states values [$\mathrm{eV^{-1}}$].
 56            d_energy: Target electron energy increment [$\mathrm{eV}$].
 57
 58        Raises:
 59            ValueError: If there are negative density values.
 60        """
 61        if np.less(values, 0.0).any():
 62            raise ValueError("Negative density values!")
 63        super().__init__(energies, values, d_energy=d_energy)
 64
 65    def ret_band_rsv(
 66        self, *, threshold: Real = 0.0
 67    ) -> BandResolvedElectronDensityOfStates:
 68        r"""Return band resolved electron density of states.
 69
 70        Args:
 71            threshold: Threshold below which electron density of states values
 72                are rounded to zero [$\mathrm{eV^{-1}}$].
 73
 74        Returns:
 75            Band resolved electron density of states.
 76        """
 77        values = self.values.copy()
 78        values[values < threshold] = 0.0
 79
 80        nonzero_i = np.where(values > 0.0)[0]
 81        d_nonzero_i = np.diff(nonzero_i)
 82        edge_i = np.where(d_nonzero_i > 1)[0] + 1
 83        band_i_seq = np.split(nonzero_i, edge_i)
 84
 85        rsv_values = {}
 86        for i, band_i in enumerate(band_i_seq):
 87            mask = np.zeros(values.shape, dtype=bool)
 88            mask[band_i] = True
 89            rsv_values[i] = np.where(mask, values, 0.0)
 90        return type(self).band_rsv(self.energies, rsv_values)
 91
 92
 93class ResolvedElectronDensityOfStates(ResolvedEnergySpectrum):
 94    r"""Resolved electron density of states.
 95
 96    Note:
 97        `energies`: Electron energies [$\mathrm{eV}$].
 98        `rsv_values`: Resolved electron density of states values
 99            [$\mathrm{eV^{-1}}$].
100    """
101
102
103class BandResolvedElectronDensityOfStates(ResolvedElectronDensityOfStates):
104    r"""Band resolved electron density of states.
105
106    Note:
107        `energies`: Electron energies [$\mathrm{eV}$].
108        `rsv_values`: Band resolved electron density of states values
109            [$\mathrm{eV^{-1}}$].
110
111    Note:
112        See `madman.analysis.spectrum.BandResolvedEnergySpectrum` for details.
113    """
114
115    def __init__(
116        self,
117        energies: Sequence[Real, ...],
118        rsv_values: Mapping[Integral, Sequence[Real, ...]],
119        *,
120        d_energy: Real | None = None,
121    ) -> None:
122        r"""Initialize BandResolvedElectronDensityOfStates object.
123
124        Args:
125            energies: Electron energies [$\mathrm{eV}$].
126            rsv_values: Mapping of band index into electron density of states
127                values [$\mathrm{eV^{-1}}$].
128            d_energy: Target electron energy increment [$\mathrm{eV}$].
129
130        Raises:
131            ValueError: If there are unresolved bands.
132            ValueError: If there are overlapping bands.
133        """
134        super().__init__(energies, rsv_values, d_energy=d_energy)
135
136        for values in self.rsv_values.values():
137            nonzero_i = np.where(values)[0]
138            d_nonzero_i = np.diff(nonzero_i)
139            if not set(d_nonzero_i).issubset({1}):
140                raise ValueError("Unresolved bands!")
141
142        for values_1, values_2 in combinations(self.rsv_values.values(), 2):
143            nonzero_i_1 = np.where(values_1)[0][:, np.newaxis]
144            nonzero_i_2 = np.where(values_2)[0]
145            if nonzero_i_1.size > 0 and nonzero_i_2.size > 0:
146                nonzero_i_d = np.abs(nonzero_i_1 - nonzero_i_2)
147                if np.amin(nonzero_i_d) <= 1:
148                    raise ValueError("Overlapping bands!")
149
150
151class CellResolvedElectronDensityOfStates(ResolvedElectronDensityOfStates):
152    r"""Cell resolved electron density of states.
153
154    Note:
155        `energies`: Electron energies [$\mathrm{eV}$].
156        `rsv_values`: Cell resolved electron density of states values
157            [$\mathrm{eV^{-1}}$].
158
159    Note:
160        See `madman.analysis.spectrum.CellResolvedEnergySpectrum` for details.
161    """
162
163    def __init__(
164        self,
165        energies: Sequence[Real, ...],
166        rsv_values: Mapping[str, Sequence[Real, ...]],
167        *,
168        d_energy: Real | None = None,
169    ) -> None:
170        r"""Initialize CellResolvedElectronDensityOfStates object.
171
172        Args:
173            energies: Electron energies [$\mathrm{eV}$].
174            rsv_values: Mapping of cell role into electron density of states
175                values [$\mathrm{eV^{-1}}$].
176            d_energy: Target electron energy increment [$\mathrm{eV}$].
177
178        Raises:
179            ValueError: If valence band is not below conduction band.
180            ValueError: If valence band is not below intermediate band.
181            ValueError: If intermediate band is not below conduction band.
182        """
183        super().__init__(energies, rsv_values, d_energy=d_energy)
184
185        if "v" in self.rsv_values and "c" in self.rsv_values:
186            vb_i = np.where(self.rsv_values["v"] > 0.0)[0]
187            cb_i = np.where(self.rsv_values["c"] > 0.0)[0]
188            if np.amin(cb_i) - np.amax(vb_i) < 2:
189                raise ValueError("Valence band not below conduction band!")
190
191        if "v" in self.rsv_values and "i" in self.rsv_values:
192            vb_i = np.where(self.rsv_values["v"] > 0.0)[0]
193            ib_i = np.where(self.rsv_values["i"] > 0.0)[0]
194            if np.amin(ib_i) - np.amax(vb_i) < 2:
195                raise ValueError("Valence band not below intermediate band!")
196
197        if "i" in self.rsv_values and "c" in self.rsv_values:
198            ib_i = np.where(self.rsv_values["i"] > 0.0)[0]
199            cb_i = np.where(self.rsv_values["c"] > 0.0)[0]
200            if np.amin(cb_i) - np.amax(ib_i) < 2:
201                raise ValueError("Intermediate band not below conduction band!")
202
203        vb_values = self.rsv_values.get("v", None)
204        if vb_values is None:
205            self._vbmax = np.nan
206        else:
207            vb_i = np.where(vb_values)[0]
208            vbmax_i = vb_i.max() + 1
209            self._vbmax = self.energies[vbmax_i]
210
211        ib_values = self.rsv_values.get("i", None)
212        if ib_values is None:
213            self._ibmin = np.nan
214            self._ibmax = np.nan
215        else:
216            ib_i = np.where(ib_values)[0]
217            ibmin_i = ib_i.min() - 1
218            ibmax_i = ib_i.max() + 1
219            self._ibmin = self.energies[ibmin_i]
220            self._ibmax = self.energies[ibmax_i]
221
222        cb_values = self.rsv_values.get("c", None)
223        if cb_values is None:
224            self._cbmin = np.nan
225        else:
226            cb_i = np.where(cb_values)[0]
227            cbmin_i = cb_i.min() - 1
228            self._cbmin = self.energies[cbmin_i]
229
230    @property
231    def vbmax(self) -> float:
232        r"""Valence band maximum [$\mathrm{eV}$]."""
233        return self._vbmax
234
235    @property
236    def ibmin(self) -> float:
237        r"""Intermediate band minimum [$\mathrm{eV}$]."""
238        return self._ibmin
239
240    @property
241    def ibmax(self) -> float:
242        r"""Intermediate band maximum [$\mathrm{eV}$]."""
243        return self._ibmax
244
245    @property
246    def cbmin(self) -> float:
247        r"""Conduction band minimum [$\mathrm{eV}$]."""
248        return self._cbmin