madman.analysis.ejdos

  1r"""Electron joint density of states."""
  2
  3from collections.abc import Sequence
  4from functools import reduce
  5from numbers import Real
  6from typing import Type
  7
  8import numpy as np
  9from matplotlib import pyplot as plt
 10
 11import madman.analysis.absorbance
 12from madman.analysis.absorbance import (
 13    SpectralAbsorbance,
 14    ResolvedSpectralAbsorbance,
 15)
 16from madman.analysis.spectrum import (
 17    EnergySpectrumMeta,
 18    EnergySpectrum,
 19    ResolvedEnergySpectrumMeta,
 20    PairResolvedEnergySpectrum,
 21    BandPairResolvedEnergySpectrum,
 22    CellPairResolvedEnergySpectrum,
 23)
 24
 25
 26class ElectronJointDensityOfStatesMeta(EnergySpectrumMeta):
 27    r"""Metaclass of ElectronJoinDensityOfStates."""
 28
 29    @property
 30    def std_axes(cls) -> plt.Axes:
 31        r"""Standard axes to plot electron joint density of states.
 32
 33        Returns:
 34            Plot axes.
 35        """
 36        _, ax = plt.subplots(tight_layout=True)
 37        ax.set_xlabel(r"Photon energy / $\mathrm{eV}$")
 38        ax.set_ylabel(r"Electron JDOS / $\mathrm{eV^{-1}}$")
 39        return ax
 40
 41
 42class ElectronJointDensityOfStates(
 43    EnergySpectrum, metaclass=ElectronJointDensityOfStatesMeta
 44):
 45    r"""Electron joint density of states.
 46
 47    Note:
 48        `energies`: Photon energies [$\mathrm{eV}$].
 49        `values`: Electron joint density of states values [$\mathrm{eV^{-1}}$].
 50    """
 51
 52    def __init__(
 53        self,
 54        energies: Sequence[Real, ...],
 55        values: Sequence[Real, ...],
 56        *,
 57        d_energy: Real | None = None,
 58    ) -> None:
 59        r"""Initialize ElectronJointDensityOfStates object.
 60
 61        Args:
 62            energies: Photon energies [$\mathrm{eV}$].
 63            values: Electron joint density of states values
 64                [$\mathrm{eV^{-1}}$].
 65            d_energy: Target photon energy increment [$\mathrm{eV}$].
 66
 67        Raises:
 68            ValueError: If there are negative values.
 69        """
 70        if np.less(values, 0.0).any():
 71            raise ValueError("Negative values!")
 72        super().__init__(energies, values, d_energy=d_energy)
 73
 74    def calc_sp_absorb(
 75        self, *, ejdos_rth: Real = 1.0, energy_co: Real | None = None
 76    ) -> SpectralAbsorbance:
 77        r"""Calculate spectral absorbance.
 78
 79        Note:
 80            By assuming that:
 81
 82            1. the optical transition matrix element is constant;
 83            2. there are enough phonons to enable indirect optical transitions;
 84
 85            the optical absorption coefficient $\alpha$ may be approximated as:
 86
 87            $$
 88            \alpha(\hbar \, \omega) \propto J(\hbar \, \omega)
 89            $$
 90
 91            where $J$ is the electron joint density of states and
 92            $\hbar \, \omega$ is the photon energy (see
 93            [O'Leary et al. (1997)](https://doi.org/10.1063/1.365643)
 94            for details).
 95
 96            By additionally assuming:
 97
 98            1. negligible reflectance $R$;
 99            2. sample thickness $l$ much larger than coherence length;
100
101            the spectral absorbance $A$ may be approximated according to
102            Beer-Lambert's law as:
103
104            $$
105            A(\hbar \, \omega) = 1 - R(\hbar \, \omega) - T(\hbar \, \omega) = 1 - \exp {\alpha(\hbar \, \omega) \, l}
106            $$
107
108            (see
109            [Fox (2010)](https://global.oup.com/academic/product/optical-properties-of-solids-9780199573370?q=978-0-19-957337-0&cc=it&lang=en)).
110
111            Then, the optical absorption coefficient is known at less than a
112            multiplicative factor, which can be incorporated into $l$, and it
113            makes sense to write:
114
115            $$
116            \alpha(\hbar \, \omega) \, l = \frac{3 \, J(\hbar \, \omega)}{\bar{J}_\text{th} \, \max{J(\hbar \, \omega)}}
117            $$
118
119            where $\bar{J}_\text{th}$ is the electron joint density of states
120            threshold relative to the electron joint density of states maximum
121            above which 95% of radiation is absorbed.
122
123        Args:
124            ejdos_rth: Electron joint density of states threshold relative to
125                the electron joint density of states maximum above which 95% of
126                radiation is absorbed.
127            energy_co: Photon energy cutoff above which absorbance is neglected.
128        """
129        if energy_co is None:
130            mask = self.energies >= 0.0
131        else:
132            mask = np.logical_and(
133                self.energies >= 0.0, self.energies <= energy_co
134            )
135        ejdos_max = np.amax(self.values)
136        norm_values = 3 * self.values / (ejdos_rth * ejdos_max)
137        sp_absorb_values = 1.0 - np.exp(-norm_values)
138        return SpectralAbsorbance(self.energies[mask], sp_absorb_values[mask])
139
140
141class ResolvedElectronJointDensityOfStatesMeta(ResolvedEnergySpectrumMeta):
142    r"""Metaclass of ResolvedElectronJointDensityOfStates."""
143
144    @property
145    def rsv_sp_absorb(cls) -> Type:
146        r"""Associated resolved spectral absorbance class."""
147        module = madman.analysis.absorbance
148        name = cls.__name__.replace(
149            "ElectronJointDensityOfStates", "SpectralAbsorbance"
150        )
151        return getattr(module, name)
152
153
154class ResolvedElectronJointDensityOfStates(
155    PairResolvedEnergySpectrum,
156    metaclass=ResolvedElectronJointDensityOfStatesMeta,
157):
158    r"""Resolved electron joint density of states.
159
160    Note:
161        `energies`: Photon energies [$\mathrm{eV}$].
162        `rsv_values`: Resolved electron joint density of states values
163            [$\mathrm{eV^{-1}}$].
164    """
165
166    def calc_rsv_sp_absorb(
167        self, *, ejdos_rth: Real = 1.0, energy_co: Real | None = None
168    ) -> ResolvedSpectralAbsorbance:
169        r"""Calculate resolved spectral absorbance.
170
171        Note:
172            See
173            `madman.analysis.ejdos.ElectronJointDensityOfStates.ret_sp_absorb`
174            for details.
175
176        Args:
177            ejdos_rth: Electron joint density of states threshold relative to
178                the electron joint density of states maximum above which 95% of
179                radiation is absorbed.
180            energy_co: Photon energy cutoff above which absorbance is neglected.
181
182        Returns:
183            Resolved spectral absorbance.
184        """
185        if energy_co is None:
186            mask = self.energies >= 0.0
187        else:
188            mask = np.logical_and(
189                self.energies >= 0.0, self.energies <= energy_co
190            )
191        energies = self.energies[mask]
192
193        ejdos_tot = self.total
194        ejdos_tot_values = ejdos_tot.values[mask]
195
196        sp_absorb_tot = ejdos_tot.calc_sp_absorb(
197            ejdos_rth=ejdos_rth, energy_co=energy_co
198        )
199        sp_absorb_tot_values = sp_absorb_tot.values
200
201        rsv_sp_absorb_values = {}
202        for feat, values in self.rsv_values.items():
203            values = values[mask]
204            rsv_sp_absorb_values[feat] = np.zeros_like(values, dtype=float)
205            for i, value in enumerate(values):
206                if ejdos_tot_values[i] != 0.0:
207                    rsv_sp_absorb_values[feat][i] = (
208                        value / ejdos_tot_values[i] * sp_absorb_tot_values[i]
209                    )
210        return type(self).rsv_sp_absorb(energies, rsv_sp_absorb_values)
211
212
213class BandResolvedElectronJointDensityOfStates(
214    BandPairResolvedEnergySpectrum, ResolvedElectronJointDensityOfStates
215):
216    r"""Band resolved electron joint density of states.
217
218    Note:
219        `energies`: Photon energies [$\mathrm{eV}$].
220        `rsv_values`: Band resolved electron joint density of states values
221            [$\mathrm{eV^{-1}}$].
222
223    Note:
224        See `madman.analysis.spectrum.BandResolvedEnergySpectrum` for details.
225    """
226
227
228class CellResolvedElectronJointDensityOfStates(
229    CellPairResolvedEnergySpectrum, ResolvedElectronJointDensityOfStates
230):
231    r"""Cell resolved electron joint density of states.
232
233    Note:
234        `energies`: Photon energies [$\mathrm{eV}$].
235        `rsv_values`: Cell resolved electron joint density of states values
236            [$\mathrm{eV^{-1}}$].
237
238    Note:
239        See `madman.analysis.spectrum.CellResolvedEnergySpectrum` for details.
240    """