scambio.absorbance

  1r"""Solar cell absorbance."""
  2
  3import numpy as np
  4import seaborn as sns
  5from collections.abc import Mapping, Sequence
  6from matplotlib import pyplot as plt
  7from numbers import Real
  8from typing import Any, Self
  9from scambio.represent import repr_poly
 10from scambio.special import rectangle
 11
 12
 13sns.set_theme(
 14    context="talk",
 15    style="white",
 16    rc={"figure.titlesize": "medium", "axes.formatter.useoffset": False},
 17)
 18
 19
 20class SpectralAbsorbancePPoly:
 21    r"""Spectral absorbance piecewise polynomial.
 22
 23    Note:
 24        Spectral absorbance is expressed as a $m$-th degree piecewise
 25        polynomial of the photon energy [$\mathrm{eV}$], specified through:
 26
 27        - photon energy partition (1d-array):
 28
 29          $$
 30          \begin{bmatrix}
 31            \epsilon_{0} & \epsilon_{1} & \dots & \epsilon_{n + 1}
 32          \end{bmatrix}
 33          $$
 34
 35          with $\epsilon_{i} < \epsilon_{i + 1}$.
 36
 37        - polynomial coefficients for each partition interval (2d-array):
 38
 39          $$
 40          \begin{bmatrix}
 41            p_{0, 0} & p_{0, 1} & \dots & p_{0, n} \\\
 42            p_{1, 0} & p_{1, 1} & \dots & p_{1, n} \\\
 43            \dots    &          &       &          \\\
 44            p_{m, 0} & p_{m, 1} & \dots & p_{m, n}
 45          \end{bmatrix}
 46          $$
 47
 48          so that:
 49
 50          $$
 51          A(\epsilon) = p_{0, i} + p_{1, i} \, \epsilon + \dots \ + p_{m, i} \, \epsilon^{m}
 52          $$
 53
 54          for $\epsilon_{i} \le \epsilon \lt \epsilon_{i + 1}$
 55
 56    Args:
 57        energy: Photon energy partition [$\mathrm{eV}$].
 58        pcoeff: Polynomial coefficients
 59            [$\mathrm{1, \dots, eV^{-j}, \dots, eV^{-m}}$].
 60    """
 61
 62    def __init__(
 63        self,
 64        energy: Sequence[Real, ...],
 65        pcoeff: Sequence[Sequence[Real, ...], ...],
 66    ) -> None:
 67        r"""Initialize SpectralAbsorbancePPoly object."""
 68        self.set_energy_and_pcoeff(energy, pcoeff)
 69
 70    def __repr__(self) -> str:
 71        r"""Represent SpectralAbsorbancePPoly object."""
 72        rows = ["Spectral absorbance:"]
 73        for i, pcoeff_i in enumerate(self.pcoeff.T):
 74            rows.append(
 75                "-"
 76                + " "
 77                + "["
 78                + f"{self.energy[i]:.2e}"
 79                + ", "
 80                + f"{self.energy[i + 1]:.2e}"
 81                + "]"
 82                + " "
 83                + "eV"
 84                + " --> "
 85                + f"{repr_poly(pcoeff_i)}"
 86            )
 87        return "\n".join(rows)
 88
 89    @property
 90    def energy(self) -> np.ndarray[float]:
 91        r"""Photon energy partition [$\mathrm{eV}$]."""
 92        return self._energy
 93
 94    @property
 95    def pcoeff(self) -> np.ndarray[float]:
 96        r"""Polynomial coefficients [$\mathrm{1, \dots, eV^{-j}, \dots, eV^{-m}}$]."""
 97        return self._pcoeff
 98
 99    @property
100    def onset(self) -> float:
101        r"""Absorption onset [$\mathrm{eV}$]."""
102        if self._onset is None:
103            self.set_onset_and_offset()
104        return self._onset
105
106    @property
107    def offset(self) -> float:
108        r"""Absorption offset [$\mathrm{eV}$]."""
109        if self._offset is None:
110            self.set_onset_and_offset()
111        return self._offset
112
113    def clear_cached_properties(self) -> None:
114        r"""Clear cached properties."""
115        self._onset = None
116        self._offset = None
117
118    def set_energy_and_pcoeff(
119        self,
120        energy: Sequence[Real, ...],
121        pcoeff: Sequence[Sequence[Real, ...], ...],
122    ) -> None:
123        r"""Set photon energy partition and polynomial coefficients.
124
125        Args:
126            energy: Photon energy partition [$\mathrm{eV}$].
127            pcoeff: Polynomial coefficients
128                [$\mathrm{1, \dots, eV^{-j}, \dots, eV^{-m}}$].
129
130        Raises:
131            ValueError: If photon energy partition is not valid, or piecewise
132                polynomial coefficients do not form a 2d-array or are not
133                commensurate with photon energy partition.
134        """
135        energy = np.asarray(energy, dtype=float)
136        if not np.array_equal(energy, np.unique(energy)):
137            raise ValueError("Invalid photon energy partition!")
138
139        pcoeff = np.asarray(pcoeff, dtype=float)
140        if not pcoeff.ndim == 2:
141            raise ValueError(
142                "Piecewise polynomial coefficients " + "do not form a 2d-array!"
143            )
144        if not pcoeff.shape[1] == energy.size - 1:
145            raise ValueError(
146                "Piecewise polynomial coefficients "
147                + "are not commensurate with photon energy partition!"
148            )
149
150        self._energy = energy
151        self._pcoeff = pcoeff
152        self.clear_cached_properties()
153
154    def set_onset_and_offset(self) -> None:
155        r"""Set absorption onset and offset."""
156        has_nonzero_absorp = self.pcoeff.any(axis=0)
157        nonzero_absorp_i = np.argwhere(has_nonzero_absorp).flatten()
158        if not nonzero_absorp_i.size > 0:
159            self._onset = np.nan
160            self._offset = np.nan
161        else:
162            onset_i = nonzero_absorp_i[0]
163            offset_i = nonzero_absorp_i[-1] + 1
164            self._onset = self.energy[onset_i]
165            self._offset = self.energy[offset_i]
166
167    def eval_sp_absorb(self, energy: Sequence[Real, ...]) -> np.ndarray[float]:
168        r"""Evaluate spectral absorbance at given photon energy values.
169
170        Args:
171            energy: Photon energy values [$\mathrm{eV}$].
172
173        Returns:
174            Spectral absorbance values.
175        """
176        energy = np.asarray(energy, dtype=float).flatten()
177        sp_absorb = np.array([], dtype=float)
178        for e in energy:
179            if e < np.amin(self.energy) or e >= np.amax(self.energy):
180                sp_absorb = np.append(sp_absorb, np.nan)
181            else:
182                i = np.searchsorted(self.energy, e, side="right")
183                pcoeff = self.pcoeff[:, i - 1]
184                sp_absorb = np.append(
185                    sp_absorb,
186                    np.polynomial.polynomial.polyval(e, pcoeff),
187                )
188        return sp_absorb
189
190    def plot_sp_absorb_vs_energy(
191        self,
192        *,
193        energy_min: Real,
194        energy_max: Real,
195        energy_inc: Real,
196        ax: plt.Axes | None = None,
197    ) -> plt.Figure | None:
198        r"""Plot spectral absorbance vs photon energy.
199
200        Args:
201            energy_min: Photon energy minimum [$\mathrm{eV}$].
202            energy_max: Photon energy maximum [$\mathrm{eV}$].
203            energy_inc: Photon energy increment [$\mathrm{eV}$].
204            ax: Plot axes. If None, new figure and axes are created.
205
206        Returns:
207            Plot figure.
208        """
209        if not 0.0 <= energy_min < energy_max < np.inf:
210            print("Photon energy range is not valid!")
211            return None
212
213        if not 0.0 < energy_inc < energy_max - energy_min:
214            print("Photon energy increment is not valid!")
215            return None
216
217        energy = np.arange(energy_min, energy_max + energy_inc, energy_inc)
218        sp_absorb = self.eval_sp_absorb(energy)
219
220        if ax is None:
221            fig, ax = plt.subplots(tight_layout=True)
222            ax.set_xlabel(r"Photon energy / eV")
223            ax.set_ylabel(r"Spectral absorbance")
224            ax.set_yticks([0.0, 0.2, 0.4, 0.6, 0.8, 1.0])
225        else:
226            fig = ax.get_figure()
227
228        ax.plot(energy, sp_absorb, color="k")
229        ax.fill_between(energy, sp_absorb, alpha=0.5)
230        return fig
231
232    @classmethod
233    def from_data(
234        cls,
235        energy: Sequence[Real, ...],
236        sp_absorb: Sequence[Real, ...],
237    ) -> Self:
238        r"""Create SpectralAbsorbancePPoly from data.
239
240        Args:
241            energy: Photon energy values [$\mathrm{eV}$].
242            sp_absorb: Spectral absorbance values.
243
244        Returns:
245            Spectral absorbance piecewise polynomial.
246
247        Raises:
248            ValueError: If there are duplicate photon energy values.
249        """
250        energy = np.asarray(energy, dtype=float).flatten()
251        sp_absorb = np.asarray(sp_absorb, dtype=float).flatten()
252
253        sort_i = np.argsort(energy)
254        energy = energy[sort_i]
255        sp_absorb = sp_absorb[sort_i]
256        sp_absorb[np.isclose(sp_absorb, 0.0)] = 0.0
257
258        if not np.array_equal(energy, np.unique(energy)):
259            raise ValueError("Duplicate photon energy values!")
260
261        slope = np.diff(sp_absorb) / np.diff(energy)
262        offset = sp_absorb[:-1] - slope * energy[:-1]
263        pcoeff = np.asarray([offset, slope])
264
265        return cls(energy, pcoeff)
266
267
268class ResolvedSpectralAbsorbancePPoly:
269    r"""Resolved spectral absorbance piecewise polynomials.
270
271    Args:
272        ii: Intermediate-intermediate spectral absorbance.
273        vi: Valence-intermediate spectral absorbance.
274        ic: Intermediate-conduction spectral absorbance.
275        vc: Valence-conduction spectral absorbance.
276    """
277
278    def __init__(
279        self,
280        *,
281        ii: SpectralAbsorbancePPoly | Any = None,
282        vi: SpectralAbsorbancePPoly | Any = None,
283        ic: SpectralAbsorbancePPoly | Any = None,
284        vc: SpectralAbsorbancePPoly | Any = None,
285    ) -> None:
286        r"""Initialize ResolvedSpectralAbsorbancePPoly object."""
287        self.set_rsv_sp_absorb_ppoly(ii=ii, vi=vi, ic=ic, vc=vc)
288
289    def __repr__(self) -> str:
290        r"""Represent ResolvedSpectralAbsorbancePPoly object."""
291        blocks = []
292        if self.ii is not None:
293            blocks.append(f"{self.ii}".replace(":", " (ii):"))
294        if self.vi is not None:
295            blocks.append(f"{self.vi}".replace(":", " (vi):"))
296        if self.ic is not None:
297            blocks.append(f"{self.ic}".replace(":", " (ic):"))
298        if self.vc is not None:
299            blocks.append(f"{self.vc}".replace(":", " (vc):"))
300        return "\n\n".join(blocks)
301
302    @property
303    def ii(self) -> SpectralAbsorbancePPoly | None:
304        r"""Intermediate-intermediate spectral absorbance."""
305        return self._ii
306
307    @property
308    def vi(self) -> SpectralAbsorbancePPoly | None:
309        r"""Valence-intermediate spectral absorbance."""
310        return self._vi
311
312    @property
313    def ic(self) -> SpectralAbsorbancePPoly | None:
314        r"""Intermediate-conduction spectral absorbance."""
315        return self._ic
316
317    @property
318    def vc(self) -> SpectralAbsorbancePPoly | None:
319        r"""Valence-conduction spectral absorbance."""
320        return self._vc
321
322    def clear_cached_properties(self) -> None:
323        r"""Clear cached properties."""
324
325    def set_rsv_sp_absorb_ppoly(
326        self,
327        *,
328        ii: SpectralAbsorbancePPoly | Any = None,
329        vi: SpectralAbsorbancePPoly | Any = None,
330        ic: SpectralAbsorbancePPoly | Any = None,
331        vc: SpectralAbsorbancePPoly | Any = None,
332    ) -> None:
333        r"""Set resolved spectral absorbance piecewise polynomials.
334
335        Args:
336            ii: Intermediate-intermediate spectral absorbance.
337            vi: Valence-intermediate spectral absorbance.
338            ic: Intermediate-conduction spectral absorbance.
339            vc: Valence-conduction spectral absorbance.
340
341        Raises:
342            ValueError: If spectral absorbance piecewise polynomials do not
343                have the same photon energy partition or degree.
344        """
345        energy_xy_seq = []
346        pcoeff_xy_seq = []
347        for xy in [ii, vi, ic, vc]:
348            if isinstance(xy, SpectralAbsorbancePPoly):
349                energy_xy_seq.append(xy.energy)
350                pcoeff_xy_seq.append(xy.pcoeff)
351
352        for energy_xy in energy_xy_seq:
353            if not np.array_equal(energy_xy, energy_xy_seq[0]):
354                raise ValueError(
355                    "Spectral absorbance piecewise polynomials "
356                    + "must have the same photon energy partition!"
357                )
358
359        for pcoeff_xy in pcoeff_xy_seq:
360            if not pcoeff_xy.shape == pcoeff_xy_seq[0].shape:
361                raise ValueError(
362                    "Spectral absorbance piecewise polynomials "
363                    + "must have the same degree!"
364                )
365
366        self._ii = ii if isinstance(ii, SpectralAbsorbancePPoly) else None
367        self._vi = vi if isinstance(vi, SpectralAbsorbancePPoly) else None
368        self._ic = ic if isinstance(ic, SpectralAbsorbancePPoly) else None
369        self._vc = vc if isinstance(vc, SpectralAbsorbancePPoly) else None
370        self.clear_cached_properties()
371
372    def plot_rsv_sp_absorb_vs_energy(
373        self,
374        *,
375        energy_min: Real,
376        energy_max: Real,
377        energy_inc: Real,
378        ax: plt.Axes | None = None,
379    ) -> plt.Figure | None:
380        r"""Plot resolved spectral absorbance vs photon energy.
381
382        Args:
383            energy_min: Photon energy minimum [$\mathrm{eV}$].
384            energy_max: Photon energy maximum [$\mathrm{eV}$].
385            energy_inc: Photon energy increment [$\mathrm{eV}$].
386            ax: Plot axes. If None, new figure and axes are created.
387
388        Returns:
389            Plot figure.
390        """
391        if not 0.0 <= energy_min < energy_max < np.inf:
392            print("Photon energy range is not valid!")
393            return None
394
395        if not 0.0 < energy_inc < energy_max - energy_min:
396            print("Photon energy increment is not valid!")
397            return None
398
399        energy = np.arange(energy_min, energy_max + energy_inc, energy_inc)
400
401        rsv_sp_absorb = {}
402        for xy in ["ii", "vi", "ic", "vc"]:
403            sp_absorb_xy_ppoly = getattr(self, xy)
404            if sp_absorb_xy_ppoly is not None:
405                sp_absorb_xy = sp_absorb_xy_ppoly.eval_sp_absorb(energy)
406            else:
407                sp_absorb_xy = 0.0 * energy
408            rsv_sp_absorb.update({xy: sp_absorb_xy})
409
410        sp_absorb_tot = np.sum(
411            [sp_absorb_xy for sp_absorb_xy in rsv_sp_absorb.values()],
412            axis=0,
413        )
414
415        if ax is None:
416            fig, ax = plt.subplots(tight_layout=True)
417            ax.set_xlabel(r"Photon energy / $\mathrm{eV}$")
418            ax.set_ylabel(r"Spectral absorbance")
419            ax.set_yticks([0.0, 0.2, 0.4, 0.6, 0.8, 1.0])
420        else:
421            fig = ax.get_figure()
422
423        ax.plot(energy, sp_absorb_tot, color="k")
424        ax.stackplot(
425            energy,
426            rsv_sp_absorb.values(),
427            labels=rsv_sp_absorb.keys(),
428        )
429        ax.legend(
430            loc="lower center",
431            bbox_to_anchor=[0.5, 1.0],
432            frameon=False,
433            ncols=len(rsv_sp_absorb),
434        )
435        return fig
436
437    @classmethod
438    def sq1961(
439        cls,
440        *,
441        bandgap_vc: Real,
442        bandwidth_vc: Real,
443    ) -> Self | None:
444        r"""Shockley-Queisser resolved spectral absorbance piecewise polynomials.
445
446        Note:
447            See [original article](https://dx.doi.org/10.1063%2F1.1736034) for
448            details.
449
450        Args:
451            bandgap_vc: Valence-conduction optical band gap [$\mathrm{eV}$].
452            bandwidth_vc: Valence-conduction optical band width [$\mathrm{eV}$].
453
454        Returns:
455            Resolved spectral absorbance piecewise polynomial.
456        """
457        if not 0.0 < bandgap_vc < np.inf:
458            print("Valence-conduction optical band gap must be finite and > 0!")
459            return None
460
461        if not 0.0 <= bandwidth_vc <= np.inf:
462            print("Valence-conduction optical band width must be nonnegative!")
463            return None
464
465        onset = bandgap_vc
466        offset = bandgap_vc + bandwidth_vc
467        energy = np.unique([0.0, onset, offset, np.inf]).astype(float)
468
469        energy_mid = 0.5 * (energy[:-1] + energy[1:])
470        sp_absorp = rectangle(energy_mid, a=onset, b=offset)
471        pcoeff = sp_absorp.reshape(1, -1)
472
473        sp_absorb_ppoly = SpectralAbsorbancePPoly(energy, pcoeff)
474        return cls(vc=sp_absorb_ppoly)
475
476    @classmethod
477    def lh2008(
478        cls,
479        *,
480        bandgap_vi: Real,
481        bandgap_ic: Real,
482        bandgap_vc: Real,
483        bandwidth_ii: Real,
484        bandwidth_vi: Real,
485        bandwidth_ic: Real,
486        bandwidth_vc: Real,
487        variant: str,
488    ) -> Self | None:
489        r"""Levi-Honsberg resolved spectral absorbance piecewise polynomials.
490
491        Note:
492            See
493            [original article](http://dx.doi.org/10.1103%2FPhysRevB.78.165122)
494            for details.
495
496        Args:
497            bandgap_vi: Valence-intermediate optical band gap [$\mathrm{eV}$].
498            bandgap_ic: Intermediate-conduction optical band gap
499                [$\mathrm{eV}$].
500            bandgap_vc: Valence-conduction optical band gap [$\mathrm{eV}$].
501            bandwidth_ii: Intermediate-intermediate optical band width
502                [$\mathrm{eV}$].
503            bandwidth_vi: Valence-intermediate optical band width
504                [$\mathrm{eV}$].
505            bandwidth_ic: Intermediate-conduction optical band width
506                [$\mathrm{eV}$].
507            bandwidth_vc: Valence-conduction optical band width [$\mathrm{eV}$].
508            variant: Model variant ('equal', 'inter', or 'intra').
509
510        Returns:
511            Resolved spectral absorbance piecewise polynomials.
512        """
513        if not (
514            0.0 < bandgap_vi < np.inf
515            and 0.0 < bandgap_ic < np.inf
516            and 0.0 < bandgap_vc < np.inf
517        ):
518            print("Optical band gaps must be finite and positive!")
519            return None
520
521        if not (
522            bandwidth_ii >= 0.0
523            and bandwidth_vi >= 0.0
524            and bandwidth_ic >= 0.0
525            and bandwidth_vc >= 0.0
526        ):
527            print("Optical band widths must be nonnegative!")
528            return None
529
530        if not bandwidth_ii < np.inf:
531            print("Intermediate band width must be finite!")
532            return None
533
534        if not variant in {"equal", "inter", "intra"}:
535            print("Variant must be 'equal', 'inter' or 'intra'!")
536            return None
537
538        if not bandgap_vi + bandgap_ic + bandwidth_ii <= bandgap_vc:
539            if np.isclose(bandgap_vi + bandgap_ic + bandwidth_ii, bandgap_vc):
540                # print("Removing floating-point representation error...")
541                bandgap_vc = bandgap_vi + bandgap_ic + bandwidth_ii
542            else:
543                print("Valence-conduction optical bandgap is too small!")
544                return None
545
546        if variant == "inter":
547            onset = [0.0]
548            offset = [min(bandwidth_ii, bandgap_vi, bandgap_ic)]
549        else:
550            onset = [0.0]
551            offset = [bandwidth_ii]
552
553        if variant == "intra":
554            onset += [
555                max(bandgap_vi, bandwidth_ii),
556                max(bandgap_ic, bandwidth_ii),
557                max(bandgap_vc, bandwidth_ii),
558            ]
559            offset += [
560                max(bandgap_vi + bandwidth_vi, bandwidth_ii),
561                max(bandgap_ic + bandwidth_ic, bandwidth_ii),
562                max(bandgap_vc + bandwidth_vc, bandwidth_ii),
563            ]
564        else:
565            onset += [bandgap_vi, bandgap_ic, bandgap_vc]
566            offset += [
567                bandgap_vi + bandwidth_vi,
568                bandgap_ic + bandwidth_ic,
569                bandgap_vc + bandwidth_vc,
570            ]
571
572        energy = np.unique([0.0, np.inf] + onset + offset).astype(float)
573
574        energy_mid = 0.5 * (energy[:-1] + energy[1:])
575        sp_absorp = rectangle(energy_mid, a=onset, b=offset)
576        sp_absorp_tot = np.sum(sp_absorp, axis=0)
577        pcoeff = sp_absorp / np.where(sp_absorp_tot == 0.0, 1.0, sp_absorp_tot)
578
579        rsv_sp_absorb_ppoly = {
580            xy: SpectralAbsorbancePPoly(energy, pcoeff_xy.reshape(1, -1))
581            for xy, pcoeff_xy in zip(["ii", "vi", "ic", "vc"], pcoeff)
582        }
583        return cls(**rsv_sp_absorb_ppoly)
584
585    @classmethod
586    def from_data(
587        cls,
588        energy: Sequence[Real, ...],
589        rsv_sp_absorb: Mapping[str, Sequence[Real, ...]],
590    ) -> Self:
591        r"""Create resolved spectral absorbance piecewise polynomials from data.
592
593        Args:
594            energy: Photon energy values [$\mathrm{eV}$].
595            rsv_sp_absorb: Mapping of electronic transition labels ('ii', 'vi',
596                'ic', 'vc') into corresponding spectral absorbance values.
597
598        Returns:
599            Resolved spectral absorbace piecewise polynomials.
600        """
601        rsv_sp_absorb = {
602            xy: SpectralAbsorbancePPoly.from_data(energy, sp_absorb_xy)
603            for xy, sp_absorb_xy in rsv_sp_absorb.items()
604            if sp_absorb_xy is not None
605        }
606        return cls(**rsv_sp_absorb)