Add abstract base class for channels

changelog/98.feature.1.rst

@@ -0,0 +1,2 @@
+Added `sunkit_instruments.response.abstractions.AbstractChannel` to standardize an interface
+for computing wavelength and temperature response functions.

changelog/98.feature.2.rst

@@ -0,0 +1,3 @@
+Added `sunkit_instruments.response.SourceSpectra` to provide a container for
+spectra as a function of temperature and wavelength needed for computing temperature
+response functions.

docs/code_ref/index.rst

@@ -14,3 +14,4 @@ API Reference
    lyra
    rhessi
    suvi
+   response

docs/code_ref/response.rst

@@ -0,0 +1,7 @@
+========
+Response
+========
+
+.. automodapi:: sunkit_instruments.response
+
+.. automodapi:: sunkit_instruments.response.abstractions

pyproject.toml

@@ -16,7 +16,8 @@ authors = [
   { name = "The SunPy Community", email = "[email protected]" },
 ]
 dependencies = [
-  "sunpy[map,net,timeseries,visualization]>=6.0.0"
+  "sunpy[map,net,timeseries,visualization]>=6.0.0",
+  "xarray>=2023.12.0",
 ]
 dynamic = ["version"]
 

pytest.ini

@@ -28,6 +28,11 @@ filterwarnings =
     error
     # Do not fail on pytest config issues (i.e. missing plugins) but do show them
     always::pytest.PytestConfigWarning
+    # A list of warnings to ignore follows. If you add to this list, you MUST
+    # add a comment or ideally a link to an issue that explains why the warning
+    # is being ignored
+    # Do not need to worry about numpy warnings raised by xarray internally
+    ignore:numpy.core.multiarray is deprecated:DeprecationWarning
     # Zeep relies on deprecated cgi in Python 3.11
     # Needs a release of zeep 4.2.2 or higher
     # https://github.com/mvantellingen/python-zeep/pull/1364

sunkit_instruments/response/__init__.py

@@ -0,0 +1,5 @@
+"""
+A subpackage for computing instrument responses
+"""
+
+from sunkit_instruments.response.thermal import SourceSpectra, get_temperature_response

sunkit_instruments/response/abstractions.py

@@ -0,0 +1,113 @@
+"""This module defines abstractions for computing instrument response."""
+import abc
+
+import astropy.units as u
+
+__all__ = ["AbstractChannel"]
+
+
+class AbstractChannel(abc.ABC):
+    """
+    An abstract base class for defining instrument channels.
+
+    For all methods and properties defined here, see the
+    topic guide on instrument response for more information.
+    """
+
+    @u.quantity_input
+    def wavelength_response(
+        self, obstime=None
+    ) -> u.cm**2 * u.DN * u.steradian / (u.photon * u.pixel):
+        """
+        Instrument response as a function of wavelength
+
+        The wavelength response is the effective area with
+        the conversion factors from photons to DN and steradians
+        to pixels.
+
+        Parameters
+        ----------
+        obstime: any format parsed by `~sunpy.time.parse_time`, optional
+            If specified, this is used to compute the time-dependent
+            instrument degradation.
+        """
+        area_eff = self.effective_area(obstime=obstime)
+        return (
+            area_eff
+            * self.energy_per_photon
+            * self.pixel_solid_angle
+            * self.camera_gain
+            / self.energy_per_electron
+        )
+
+    @u.quantity_input
+    def effective_area(self, obstime=None) -> u.cm**2:
+        """
+        Effective area as a function of wavelength.
+
+        The effective area is the geometrical collecting area
+        weighted by the mirror reflectance, filter transmittance,
+        quantum efficiency, and instrument degradation.
+
+        Parameters
+        ----------
+        obstime: any format parsed by `sunpy.time.parse_time`, optional
+            If specified, this is used to compute the time-dependent
+            instrument degradation.
+        """
+        return (
+            self.geometrical_area
+            * self.mirror_reflectance
+            * self.filter_transmittance
+            * self.effective_quantum_efficiency
+            * self.degradation(obstime=obstime)
+        )
+
+    @property
+    @u.quantity_input
+    def energy_per_photon(self) -> u.eV / u.photon:
+        return self.wavelength.to("eV", equivalencies=u.spectral()) / u.photon
+
+    @abc.abstractmethod
+    @u.quantity_input
+    def degradation(self, obstime=None) -> u.dimensionless_unscaled: ...
+
+    @property
+    @abc.abstractmethod
+    @u.quantity_input
+    def geometrical_area(self) -> u.cm**2: ...
+
+    @property
+    @abc.abstractmethod
+    @u.quantity_input
+    def mirror_reflectance(self) -> u.dimensionless_unscaled: ...
+
+    @property
+    @abc.abstractmethod
+    @u.quantity_input
+    def filter_transmittance(self) -> u.dimensionless_unscaled: ...
+
+    @property
+    @abc.abstractmethod
+    @u.quantity_input
+    def effective_quantum_efficiency(self) -> u.dimensionless_unscaled: ...
+
+    @property
+    @abc.abstractmethod
+    @u.quantity_input
+    def camera_gain(self) -> u.DN / u.electron: ...
+
+    @property
+    @abc.abstractmethod
+    @u.quantity_input
+    def energy_per_electron(self) -> u.eV / u.electron: ...
+
+    @property
+    @abc.abstractmethod
+    @u.quantity_input
+    def pixel_solid_angle(self) -> u.steradian / u.pixel: ...
+
+    @property
+    @abc.abstractmethod
+    @u.quantity_input
+    def wavelength(self) -> u.Angstrom: ...

sunkit_instruments/response/tests/test_channel.py

@@ -0,0 +1,92 @@
+import numpy as np
+import pytest
+
+import astropy.units as u
+
+from sunkit_instruments.response import SourceSpectra
+from sunkit_instruments.response.abstractions import AbstractChannel
+
+
+class TestChannel(AbstractChannel):
+    @property
+    @u.quantity_input
+    def wavelength(self) -> u.Angstrom:
+        return np.linspace(100, 200, 100) * u.AA
+
+    @u.quantity_input
+    def degradation(self, obstime=None) -> u.dimensionless_unscaled:
+        return 1.0
+
+    @property
+    @u.quantity_input
+    def geometrical_area(self) -> u.cm**2:
+        return 10 * u.cm**2
+
+    @property
+    @u.quantity_input
+    def mirror_reflectance(self) -> u.dimensionless_unscaled:
+        return np.exp(
+            -((self.wavelength - self.wavelength[0]) / self.wavelength[0]).decompose()
+        )
+
+    @property
+    @u.quantity_input
+    def filter_transmittance(self) -> u.dimensionless_unscaled:
+        return np.exp(
+            -((self.wavelength - 150 * u.AA) ** 2 / (1 * u.AA) ** 2).decompose()
+        )
+
+    @property
+    @u.quantity_input
+    def effective_quantum_efficiency(self) -> u.dimensionless_unscaled:
+        return np.ones(self.wavelength.shape)
+
+    @property
+    @u.quantity_input
+    def camera_gain(self) -> u.DN / u.electron:
+        return 2 * u.DN / u.electron
+
+    @property
+    @u.quantity_input
+    def energy_per_electron(self) -> u.eV / u.electron:
+        return 3.65 * u.eV / u.electron
+
+    @property
+    @u.quantity_input
+    def pixel_solid_angle(self) -> u.steradian / u.pixel:
+        return (1 * u.arcsec) ** 2 / u.pixel
+
+
+@pytest.fixture
+def fake_channel():
+    return TestChannel()
+
+
+def test_effective_area(fake_channel):
+    assert isinstance(fake_channel.effective_area(), u.Quantity)
+
+
+def test_wavelength_response(fake_channel):
+    assert isinstance(fake_channel.wavelength_response(), u.Quantity)
+
+
+@pytest.fixture
+def fake_spectra():
+    temperature = np.logspace(5, 8, 100) * u.K
+    density = 1e15 * u.cm ** (-3) * u.K / temperature
+    wavelength = np.linspace(50, 250, 1000) * u.AA
+    data = np.random.rand(*temperature.shape + wavelength.shape) * u.Unit(
+        "photon cm3 s-1 sr-1 Angstrom-1"
+    )
+    return SourceSpectra(temperature, wavelength, data, density=density)
+
+
+def test_spectra_repr(fake_spectra):
+    assert isinstance(fake_spectra.__repr__(), str)
+
+
+@pytest.mark.parametrize('obstime', [None, '2020-01-01'])
+def test_temperature_response(fake_channel, fake_spectra, obstime):
+    temp_response = fake_spectra.temperature_response(fake_channel, obstime=obstime)
+    assert isinstance(temp_response, u.Quantity)
+    assert temp_response.shape == fake_spectra.temperature.shape