scambio.balance

  1r"""Solar cell detailed balance model."""
  2
  3import numpy as np
  4from collections.abc import Mapping, Sequence
  5from numbers import Real
  6from scipy.optimize import root_scalar
  7from typing import Self
  8from scambio.absorbance import (
  9    ResolvedSpectralAbsorbancePPoly,
 10    SpectralAbsorbancePPoly,
 11)
 12from scambio.constant import Constant
 13from scambio.special import bose_einstein_integr
 14
 15
 16class RadiativeExchangeChannel:
 17    r"""Radiative exchange channel.
 18
 19    Args:
 20        sp_absorb_ppoly: Spectral absorbance piecewise polynomial.
 21        temperature: Temperature [$\mathrm{K}$].
 22        potential: Chemical potential [$\mathrm{eV}$].
 23        concentration: Sunlight concentration factor.
 24
 25    Raises:
 26        TypeError: If sp_absorb_ppoly is not a SpectralAbsorbancePPoly object.
 27        ValueError: If temperature, chemical potential, or sunlight
 28            concentration factor are unphysical.
 29    """
 30
 31    def __init__(
 32        self,
 33        sp_absorb_ppoly: SpectralAbsorbancePPoly,
 34        *,
 35        temperature: Real,
 36        potential: Real,
 37        concentration: Real,
 38    ) -> None:
 39        r"""Initialize RadiativeExchangeChannel object."""
 40        self.sp_absorb_ppoly = sp_absorb_ppoly
 41        self.temperature = temperature
 42        self.potential = potential
 43        self.concentration = concentration
 44
 45    @property
 46    def sp_absorb_ppoly(self) -> SpectralAbsorbancePPoly:
 47        r"""Spectral absorbance piecewise polynomial."""
 48        return self._sp_absorb_ppoly
 49
 50    @sp_absorb_ppoly.setter
 51    def sp_absorb_ppoly(self, arg: SpectralAbsorbancePPoly) -> None:
 52        if not isinstance(arg, SpectralAbsorbancePPoly):
 53            raise TypeError("Not a SpectralAbsorbancePPoly object!")
 54        self._sp_absorb_ppoly = arg
 55        self.clear_cached_properties()
 56
 57    @property
 58    def temperature(self) -> float:
 59        r"""Temperature [$\mathrm{K}$]."""
 60        return self._temperature
 61
 62    @temperature.setter
 63    def temperature(self, arg: Real) -> None:
 64        if not isinstance(arg, Real) or not arg > 0.0:
 65            raise ValueError("Temperature must be a positive number!")
 66        self._temperature = float(arg)
 67        self.clear_cached_properties()
 68
 69    @property
 70    def potential(self) -> float:
 71        r"""Chemical potential [$\mathrm{eV}$]."""
 72        return self._potential
 73
 74    @potential.setter
 75    def potential(self, arg: Real) -> None:
 76        if not isinstance(arg, Real):
 77            raise ValueError("Chemical potential must be a real number!")
 78        self._potential = float(arg)
 79        self.clear_cached_properties()
 80
 81    @property
 82    def concentration(self) -> float:
 83        r"""Sunlight concentration factor."""
 84        return self._concentration
 85
 86    @concentration.setter
 87    def concentration(self, arg: Real) -> None:
 88        if not isinstance(arg, Real) or not (0.0 <= arg <= 46200.0):
 89            raise ValueError(
 90                "Sunlight concentration factor must be between 0 and 46200!"
 91            )
 92        self._concentration = float(arg)
 93        self.clear_cached_properties()
 94
 95    @property
 96    def phot_flux(self) -> float:
 97        r"""Photon flux density [$\mathrm{s^{-1} \, cm^{-2}}$]."""
 98        if self._phot_flux is None:
 99            self._phot_flux = 0.0
100            if not np.isnan(self.sp_absorb_ppoly.onset):
101                for i, pcoeff_i in enumerate(self.sp_absorb_ppoly.pcoeff.T):
102                    energy_lb = self.sp_absorb_ppoly.energy[i]
103                    energy_ub = self.sp_absorb_ppoly.energy[i + 1]
104                    for j, pcoeff_ij in enumerate(pcoeff_i):
105                        if pcoeff_ij != 0.0:
106                            order = 2 + j
107                            self._phot_flux += pcoeff_ij * (
108                                bose_einstein_integr(
109                                    order,
110                                    energy_lb,
111                                    temperature=self.temperature,
112                                    potential=self.potential,
113                                )
114                                - bose_einstein_integr(
115                                    order,
116                                    energy_ub,
117                                    temperature=self.temperature,
118                                    potential=self.potential,
119                                )
120                            )
121                            if self.concentration != 0.0:
122                                self._phot_flux -= (
123                                    pcoeff_ij
124                                    * self.concentration
125                                    * Constant.fsun
126                                    * (
127                                        bose_einstein_integr(
128                                            order,
129                                            energy_lb,
130                                            temperature=Constant.tsun,
131                                            potential=Constant.usun,
132                                        )
133                                        - bose_einstein_integr(
134                                            order,
135                                            energy_ub,
136                                            temperature=Constant.tsun,
137                                            potential=Constant.usun,
138                                        )
139                                    )
140                                )
141        return self._phot_flux
142
143    def clear_cached_properties(self) -> None:
144        r"""Clear cached properties."""
145        self._phot_flux = None
146
147
148class DetailedBalanceModel:
149    r"""Solar cell detailed balance model.
150
151    Note:
152        Applicable to Shockley-Queisser and intermediate band solar cells.
153
154    Args:
155        rsv_sp_absorb_ppoly: Resolved spectral absorbance piecewise polynomials.
156        temperature: Temperature [$\mathrm{K}$].
157        voltage: Voltage [$\mathrm{V}$].
158        concentration: Sunlight concentration factor.
159
160    Raises:
161        TypeError: If rsv_sp_absorb_ppoly is not a
162            ResolvedSpectralAbsorbancePPoly object.
163        ValueError: If temperature, voltage, or sunlight concentration factor
164            are unphysical.
165    """
166
167    def __init__(
168        self,
169        rsv_sp_absorb_ppoly: ResolvedSpectralAbsorbancePPoly,
170        *,
171        temperature: Real,
172        voltage: Real,
173        concentration: Real,
174    ) -> None:
175        r"""Initialize RadiativeExchangeSystem object."""
176        self.rsv_sp_absorb_ppoly = rsv_sp_absorb_ppoly
177        self.temperature = temperature
178        self.voltage = voltage
179        self.concentration = concentration
180
181    @property
182    def rsv_sp_absorb_ppoly(self) -> ResolvedSpectralAbsorbancePPoly:
183        r"""Resolved spectral absorbance piecewise polynomials."""
184        return self._rsv_sp_absorb_ppoly
185
186    @rsv_sp_absorb_ppoly.setter
187    def rsv_sp_absorb_ppoly(self, arg: ResolvedSpectralAbsorbancePPoly) -> None:
188        if not isinstance(arg, ResolvedSpectralAbsorbancePPoly):
189            raise TypeError("Not a ResolvedSpectralAbsorbancePPoly object!")
190        self._rsv_sp_absorb_ppoly = arg
191
192    @property
193    def temperature(self) -> float:
194        r"""Temperature [$\mathrm{K}$]."""
195        return self._temperature
196
197    @temperature.setter
198    def temperature(self, arg: Real) -> None:
199        if not isinstance(arg, Real) or not arg > 0.0:
200            raise ValueError("Temperature must be a positive number!")
201        self._temperature = float(arg)
202        self.clear_cached_properties()
203
204    @property
205    def voltage(self) -> float:
206        r"""Voltage [$\mathrm{V}$]."""
207        return self._voltage
208
209    @voltage.setter
210    def voltage(self, arg: Real) -> None:
211        if not isinstance(arg, Real):
212            raise ValueError("Voltage must be a real number!")
213        self._voltage = float(arg)
214        self.clear_cached_properties()
215
216    @property
217    def concentration(self) -> float:
218        r"""Sunlight concentration factor."""
219        return self._concentration
220
221    @concentration.setter
222    def concentration(self, arg: Real) -> None:
223        if not isinstance(arg, Real) or not (0.0 <= arg <= 46200.0):
224            raise ValueError(
225                "Sunlight concentration factor must be between 0 and 46200!"
226            )
227        self._concentration = float(arg)
228        self.clear_cached_properties()
229
230    @property
231    def voltage_ub(self) -> float:
232        r"""Voltage upper bound [$\mathrm{V}$]."""
233        if self._voltage_ub is None:
234            sp_absorb_vi = self.rsv_sp_absorb_ppoly.vi
235            sp_absorb_ic = self.rsv_sp_absorb_ppoly.ic
236            if (
237                sp_absorb_vi is not None
238                and not np.isnan(sp_absorb_vi.onset)
239                and sp_absorb_ic is not None
240                and not np.isnan(sp_absorb_ic.onset)
241            ):
242                voltage_ub = sp_absorb_vi.onset + sp_absorb_ic.onset
243            else:
244                sp_absorb_vc = self.rsv_sp_absorb_ppoly.vc
245                if sp_absorb_vc is not None and not np.isnan(
246                    sp_absorb_vc.onset
247                ):
248                    voltage_ub = sp_absorb_vc.onset
249                else:
250                    voltage_ub = np.inf
251            self._voltage_ub = float(voltage_ub)
252        return self._voltage_ub
253
254    @property
255    def potential_vi_lb(self) -> float:
256        r"""Valence-intermediate chemical potential lower bound [$\mathrm{eV}$]."""
257        if self._potential_vi_lb is None:
258            sp_absorb_ic = self.rsv_sp_absorb_ppoly.ic
259            if self.voltage < self.voltage_ub and sp_absorb_ic is not None:
260                onset_ic = sp_absorb_ic.onset
261                self._potential_vi_lb = self.voltage - onset_ic
262            else:
263                self._potential_vi_lb = np.nan
264        return self._potential_vi_lb
265
266    @property
267    def potential_vi_ub(self) -> float:
268        r"""Valence-intermediate chemical potential upper bound [$\mathrm{eV}$]."""
269        if self._potential_vi_ub is None:
270            sp_absorb_vi = self.rsv_sp_absorb_ppoly.vi
271            if sp_absorb_vi is not None:
272                onset_vi = sp_absorb_vi.onset
273                self._potential_vi_ub = onset_vi
274            else:
275                self._potential_vi_ub = np.nan
276        return self._potential_vi_ub
277
278    @property
279    def potential_ii(self) -> float:
280        r"""Intermediate-intermediate chemical potential [$\mathrm{eV}$]."""
281        if self._potential_ii is None:
282            if self.rsv_sp_absorb_ppoly.ii is None:
283                self._potential_ii = np.nan
284            else:
285                self._potential_ii = 0.0
286        return self._potential_ii
287
288    @property
289    def potential_vi(self) -> float:
290        r"""Valence-intermediate chemical potential [$\mathrm{eV}$]."""
291        if self._potential_vi is None:
292            if self.voltage >= self.voltage_ub:
293                self._potential_vi = np.nan
294            elif np.isnan(self.potential_vi_lb) and np.isnan(
295                self.potential_vi_ub
296            ):
297                self._potential_vi = np.nan
298            else:
299                if np.isnan(self.potential_vi_lb):
300                    potential_vi_b = self.potential_vi_ub
301                    potential_vi_a = potential_vi_b - 0.1
302                    curr_den_ib_a = self.curr_den_ib_vs_potential_vi(
303                        potential_vi_a
304                    )
305                    while curr_den_ib_a <= 0.0:
306                        potential_vi_a -= 0.1
307                        curr_den_ib_a = self.curr_den_ib_vs_potential_vi(
308                            potential_vi_a
309                        )
310                elif np.isnan(self.potential_vi_ub):
311                    potential_vi_a = self.potential_vi_lb
312                    potential_vi_b = potential_vi_a + 0.1
313                    curr_den_ib_b = self.curr_den_ib_vs_potential_vi(
314                        potential_vi_b
315                    )
316                    while curr_den_ib_b >= 0.0:
317                        potential_vi_b += 0.1
318                        curr_den_ib_b = self.curr_den_ib_vs_potential_vi(
319                            potential_vi_b
320                        )
321                else:
322                    potential_vi_a = self.potential_vi_lb
323                    potential_vi_b = self.potential_vi_ub
324
325                def objective(potential_vi):
326                    if potential_vi == potential_vi_a:
327                        return np.inf
328                    elif potential_vi == potential_vi_b:
329                        return -np.inf
330                    else:
331                        return self.curr_den_ib_vs_potential_vi(potential_vi)
332
333                sol = root_scalar(
334                    objective,
335                    method="brentq",
336                    bracket=[potential_vi_a, potential_vi_b],
337                )
338                if not sol.converged:
339                    print(
340                        "Intermediate-valence chemical potential "
341                        + "did not converge!"
342                    )
343                    self._potential_vi = np.nan
344                else:
345                    self._potential_vi = sol.root
346
347        return self._potential_vi
348
349    @property
350    def potential_ic(self) -> float:
351        r"""Intermediate-conduction chemical potential [$\mathrm{eV}$]."""
352        if self._potential_ic is None:
353            self._potential_ic = self.potential_vc - self.potential_vi
354        return self._potential_ic
355
356    @property
357    def potential_vc(self) -> float:
358        r"""Valence-conduction chemical potential [$\mathrm{eV}$]."""
359        if self._potential_vc is None:
360            if self.voltage >= self.voltage_ub:
361                self._potential_vc = np.nan
362            else:
363                self._potential_vc = self.voltage
364        return self._potential_vc
365
366    @property
367    def phot_flux_ii(self) -> float:
368        r"""Intermediate-intermediate photon flux density [$\mathrm{s^{-1} \, cm^{-2}}$]."""
369        if self._phot_flux_ii is None:
370            if self.rsv_sp_absorb_ppoly.ii is None:
371                self._phot_flux_ii = 0.0
372            else:
373                self._phot_flux_ii = RadiativeExchangeChannel(
374                    self.rsv_sp_absorb_ppoly.ii,
375                    temperature=self.temperature,
376                    potential=self.potential_ii,
377                    concentration=self.concentration,
378                ).phot_flux
379        return self._phot_flux_ii
380
381    @property
382    def phot_flux_vi(self) -> float:
383        r"""Valence-intermediate photon flux density [$\mathrm{s^{-1} \, cm^{-2}}$]."""
384        if self._phot_flux_vi is None:
385            self._phot_flux_vi = self.phot_flux_vi_vs_potential_vi(
386                self.potential_vi
387            )
388        return self._phot_flux_vi
389
390    @property
391    def phot_flux_ic(self) -> float:
392        r"""Intermediate-conduction photon flux density [$\mathrm{s^{-1} \, cm^{-2}}$]."""
393        if self._phot_flux_ic is None:
394            self._phot_flux_ic = self.phot_flux_ic_vs_potential_vi(
395                self.potential_vi
396            )
397        return self._phot_flux_ic
398
399    @property
400    def phot_flux_vc(self) -> float:
401        r"""Valence-conduction photon flux density [$\mathrm{s^{-1} \, cm^{-2}}$]."""
402        if self._phot_flux_vc is None:
403            if self.rsv_sp_absorb_ppoly.vc is None:
404                self._phot_flux_vc = 0.0
405            else:
406                self._phot_flux_vc = RadiativeExchangeChannel(
407                    self.rsv_sp_absorb_ppoly.vc,
408                    temperature=self.temperature,
409                    potential=self.potential_vc,
410                    concentration=self.concentration,
411                ).phot_flux
412        return self._phot_flux_vc
413
414    @property
415    def curr_den_ib(self) -> float:
416        r"""Intermediate-band current density [$\mathrm{mA \, cm^{-2}}$]."""
417        if self._curr_den_ib is None:
418            self._curr_den_ib = Constant.q * (
419                self.phot_flux_ic - self.phot_flux_vi
420            )
421        return self._curr_den_ib
422
423    @property
424    def curr_den_vb(self) -> float:
425        r"""Valence band current density [$\mathrm{mA \, cm^{-2}}$]."""
426        if self._curr_den_vb is None:
427            self._curr_den_vb = Constant.q * (
428                self.phot_flux_vc + self.phot_flux_vi
429            )
430        return self._curr_den_vb
431
432    @property
433    def curr_den_cb(self) -> float:
434        r"""Conduction band current density [$\mathrm{mA \, cm^{-2}}$]."""
435        if self._curr_den_cb is None:
436            self._curr_den_cb = Constant.q * (
437                self.phot_flux_vc + self.phot_flux_ic
438            )
439        return self._curr_den_cb
440
441    def clear_cached_properties(self) -> None:
442        r"""Clear cached properties."""
443        self._voltage_ub = None
444        self._potential_vi_lb = None
445        self._potential_vi_ub = None
446        self._potential_ii = None
447        self._potential_vi = None
448        self._potential_ic = None
449        self._potential_vc = None
450        self._phot_flux_ii = None
451        self._phot_flux_vi = None
452        self._phot_flux_ic = None
453        self._phot_flux_vc = None
454        self._curr_den_ib = None
455        self._curr_den_vb = None
456        self._curr_den_cb = None
457
458    def phot_flux_vi_vs_potential_vi(self, potential_vi: Real) -> float:
459        r"""Valence-intermediate photon flux density vs chemical potential.
460
461        Args:
462            potential_vi: Valence-intermediate chemical potential
463                [$\mathrm{eV}$].
464
465        Returns:
466            Valence-intermediate photon flux density
467            [$\mathrm{s^{-1} \, cm^{-2}}$].
468        """
469        if self.rsv_sp_absorb_ppoly.vi is None:
470            return 0.0
471        else:
472            return RadiativeExchangeChannel(
473                self.rsv_sp_absorb_ppoly.vi,
474                temperature=self.temperature,
475                potential=potential_vi,
476                concentration=self.concentration,
477            ).phot_flux
478
479    def phot_flux_ic_vs_potential_vi(self, potential_vi: Real) -> float:
480        r"""Intermediate-conduction photon flux density vs valence-intermediate chemical potential.
481
482        Args:
483            potential_vi: Valence-intermediate chemical potential [$\mathrm{eV}$].
484
485        Returns:
486            Intermediate-conduction photon flux density
487            [$\mathrm{s^{-1} \, cm^{-2}}$].
488        """
489        if self.rsv_sp_absorb_ppoly.ic is None:
490            return 0.0
491        else:
492            return RadiativeExchangeChannel(
493                self.rsv_sp_absorb_ppoly.ic,
494                temperature=self.temperature,
495                potential=self.potential_vc - potential_vi,
496                concentration=self.concentration,
497            ).phot_flux
498
499    def curr_den_ib_vs_potential_vi(self, potential_vi: Real):
500        r"""Intermediate band current density vs vi chemical potential.
501
502        Args:
503            potential_vi: Valence-intermediate chemical potential
504                [$\mathrm{eV}$].
505
506        Returns:
507            Intermediate band current density [$\mathrm{mA \, cm^{-2}}$].
508        """
509        phot_flux_vi = self.phot_flux_vi_vs_potential_vi(potential_vi)
510        phot_flux_ic = self.phot_flux_ic_vs_potential_vi(potential_vi)
511        return Constant.q * (phot_flux_ic - phot_flux_vi)
512
513    @classmethod
514    def sq1961(
515        cls,
516        *,
517        bandgap_vc: Real,
518        bandwidth_vc: Real,
519        temperature: Real,
520        voltage: Real,
521        concentration: Real,
522    ) -> Self | None:
523        r"""Shockley-Queisser detailed balance model.
524
525        Note:
526            See [original article](https://dx.doi.org/10.1063%2F1.1736034) for
527            details.
528
529        Args:
530            bandgap_vc: Valence-conduction optical band gap [$\mathrm{eV}$].
531            bandwidth_vc: Valence-conduction optical band width [$\mathrm{eV}$].
532            temperature: Temperature [$\mathrm{K}$].
533            voltage: Voltage [$\mathrm{V}$].
534            concentration: Sunlight concentration factor.
535
536        Returns:
537            Detailed balance model.
538        """
539        rsv_sp_absorb_ppoly = ResolvedSpectralAbsorbancePPoly.sq1961(
540            bandgap_vc=bandgap_vc,
541            bandwidth_vc=bandwidth_vc,
542        )
543        if rsv_sp_absorb_ppoly is None:
544            return None
545        else:
546            return cls(
547                rsv_sp_absorb_ppoly,
548                temperature=temperature,
549                voltage=voltage,
550                concentration=concentration,
551            )
552
553    @classmethod
554    def lh2008(
555        cls,
556        *,
557        bandgap_vi: Real,
558        bandgap_ic: Real,
559        bandgap_vc: Real,
560        bandwidth_ii: Real,
561        bandwidth_vi: Real,
562        bandwidth_ic: Real,
563        bandwidth_vc: Real,
564        variant: str,
565        temperature: Real,
566        voltage: Real,
567        concentration: Real,
568    ) -> Self | None:
569        r"""Levi-Honsberg detailed balance model.
570
571        Note:
572            See
573            [original article](http://dx.doi.org/10.1103%2FPhysRevB.78.165122)
574            for details.
575
576        Args:
577            bandgap_vi: Valence-intermediate optical band gap [$\mathrm{eV}$].
578            bandgap_ic: Intermediate-conduction optical band gap
579                [$\mathrm{eV}$].
580            bandgap_vc: Valence-conduction optical band gap [$\mathrm{eV}$].
581            bandwidth_ii: Intermediate-intermediate optical band width
582                [$\mathrm{eV}$].
583            bandwidth_vi: Valence-intermediate optical band width
584                [$\mathrm{eV}$].
585            bandwidth_ic: Intermediate-conduction optical band width
586                [$\mathrm{eV}$].
587            bandwidth_vc: Valence-conduction optical band width [$\mathrm{eV}$].
588            variant: Model variant ('equal', 'inter', or 'intra').
589            temperature: Temperature [$\mathrm{K}$].
590            voltage: Voltage [$\mathrm{V}$].
591            concentration: Sunlight concentration factor.
592
593        Returns:
594            Detailed balance model.
595        """
596        rsv_sp_absorb_ppoly = ResolvedSpectralAbsorbancePPoly.lh2008(
597            bandgap_vi=bandgap_vi,
598            bandgap_ic=bandgap_ic,
599            bandgap_vc=bandgap_vc,
600            bandwidth_ii=bandwidth_ii,
601            bandwidth_vi=bandwidth_vi,
602            bandwidth_ic=bandwidth_ic,
603            bandwidth_vc=bandgap_vc,
604        )
605        if rsv_sp_absorb_ppoly is None:
606            return None
607        else:
608            return cls(
609                rsv_sp_absorb_ppoly,
610                temperature=temperature,
611                voltage=voltage,
612                concentration=concentration,
613            )
614
615    @classmethod
616    def from_data(
617        cls,
618        energy: Sequence[Real, ...],
619        rsv_sp_absorb: Mapping[str, Sequence[Real, ...]],
620        *,
621        temperature: Real,
622        voltage: Real,
623        concentration: Real,
624    ) -> Self:
625        r"""Create detailed balance model from data.
626
627        Args:
628            energy: Photon energy values [$\mathrm{eV}$].
629            rsv_sp_absorb: Mapping of band pair labels ('ii', 'vi', 'ic', 'vc')
630                into corresponding spectral absorbance values.
631            temperature: Temperature [$\mathrm{K}$].
632            voltage: Voltage [$\mathrm{V}$].
633            concentration: Sunlight concentration factor.
634
635        Returns:
636            Detailed balance model.
637        """
638        rsv_sp_absorb_ppoly = ResolvedSpectralAbsorbancePPoly.from_data(
639            energy,
640            rsv_sp_absorb,
641        )
642        if rsv_sp_absorb_ppoly is None:
643            return None
644        else:
645            return cls(
646                rsv_sp_absorb_ppoly,
647                temperature=temperature,
648                voltage=voltage,
649                concentration=concentration,
650            )