Partial updates for new method names.

Author: mkelley

docs/sbpy/surfaces.rst

@@ -1,6 +1,11 @@
 Surfaces Module (`sbpy.surfaces`)
 =================================
 
+.. admonition:: warning
+
+    The surface module is being made available on a preview basis.  The API is
+    subject to change.  Feedback on the approach used is welcome.
+
 The ``surfaces`` module describes the interaction of electromagnetic radiation with surfaces.  Sbpy uses the :math:`(i, e, \phi)` model (angle of incidence, angle of emittance, and phase angle) to describe how light scatters and emits light.  It has a flexible system that can incorporate any surface scattering model that can be described with these three angles.  A few built-in surface models are provided.
 
 .. figure:: ../static/scattering-vectors.svg

sbpy/surfaces/lambertian.py

@@ -1,28 +1,45 @@
 # Licensed under a 3-clause BSD style license - see LICENSE.rst
 
+import numpy as np
 import astropy.units as u
 
 from .surface import Surface
+from ..units.typing import SpectralFluxDensityQuantity
 
 
 class LambertianSurface(Surface):
     """Abstract base class for Lambertian surfaces."""
 
     @u.quantity_input
-    def absorptance(self, i: u.physical.angle) -> u.Quantity:
-        # use self._min_zero_cos(i) which ensures cos(>= 90 deg) = 0
+    def absorption(
+        self,
+        F_i: SpectralFluxDensityQuantity,
+        i: u.physical.angle,
+    ) -> u.Quantity:
+        # use self._min_zero_cos(i) to ensure cos(>= 90 deg) = 0
         cos_i = self._min_zero_cos(i)
-        return (1 - self.phys["albedo"]) * cos_i
+        return F_i * (1 - self.phys["albedo"]) * cos_i
 
     @u.quantity_input
-    def emittance(self, e: u.physical.angle, phi: u.physical.angle) -> u.Quantity:
-        # use self._min_zero_cos(e) which ensures cos(>= 90 deg) = 0
-        return self._min_zero_cos(e)
+    def emission(
+        self,
+        X_e: SpectralFluxDensityQuantity,
+        e: u.physical.angle,
+        phi: u.physical.angle,
+    ) -> u.Quantity:
+        # use self._min_zero_cos(e) to ensure cos(>= 90 deg) = 0
+        cos_e = self._min_zero_cos(e)
+        return X_e * cos_e / np.pi / u.sr
 
     @u.quantity_input
     def reflectance(
-        self, i: u.physical.angle, e: u.physical.angle, phi: u.physical.angle
+        self,
+        F_i: SpectralFluxDensityQuantity,
+        i: u.physical.angle,
+        e: u.physical.angle,
+        phi: u.physical.angle,
     ) -> u.Quantity:
-        # use self._min_zero_cos(e) which ensures cos(>= 90 deg) = 0
+        # use self._min_zero_cos(theta) to ensure cos(>= 90 deg) = 0
         cos_i = self._min_zero_cos(i)
-        return self.phys["albedo"] * cos_i * self.emittance(e, phi)
+        cos_e = self._min_zero_cos(e)
+        return F_i * self.phys["albedo"] * cos_i * cos_e / np.pi

sbpy/surfaces/scattered.py

@@ -10,26 +10,7 @@
 from ..units.typing import SpectralQuantity, SpectralFluxDensityQuantity, UnitLike
 
 
-class ScatteredLight(Surface):
-    """Abstract base class to observe light scattered by a surface."""
-
-    @u.quantity_input
-    def radiance(
-        self,
-        F_i: SpectralFluxDensityQuantity,
-        i: u.physical.angle,
-        e: u.physical.angle,
-        phi: u.physical.angle,
-    ) -> u.Quantity:
-        """Observed light reflected from a surface."""
-        return F_i * self.reflectance(i, e, phi) / u.sr
-
-    radiance.__doc__ += Surface.radiance.__doc__[
-        Surface.radiance.__doc__.index("\n") :  # noqa: E203
-    ]
-
-
-class ScatteredSunlight(ScatteredLight):
+class ScatteredSunlight(Surface):
     """Abstract base class to observe sunlight scattered by a surface."""
 
     @u.quantity_input
@@ -82,7 +63,7 @@ def scattered_sunlight(
             F_i = sun.observe(wave_freq, unit=flux_density_unit)
 
         F_i /= rh.to_value("au") ** 2
-        return self.radiance(F_i, i, e, phi).to(unit)
+        return self.reflectance(F_i, i, e, phi).to(unit)
 
     @u.quantity_input
     def scattered_sunlight_from_vectors(

sbpy/surfaces/surface.py

@@ -39,47 +39,63 @@ def _min_zero_cos(a: u.physical.angle) -> u.Quantity:
         return np.maximum(x, 0)
 
     @abstractmethod
-    def absorptance(self, i: u.physical.angle) -> u.Quantity:
-        r"""Absorption of incident light.
+    def absorption(
+        self,
+        F_i: SpectralFluxDensityQuantity,
+        i: u.physical.angle,
+    ) -> u.Quantity:
+        r"""Absorption of directional, incident light.
 
         The surface is illuminated by incident flux density, :math:`F_i`, at an
         angle of :math:`i`, measured from the surface normal direction.
 
 
         Parameters
         ----------
+        F_i : `astropy.units.Quantity`
+            Incident light (spectral flux density / spectral irradiance).
+
         i : `~astropy.units.Quantity`
             Angle from normal of incident light.
 
 
         Returns
         -------
-        a : `~astropy.units.Quantity`
-            Surface absorptance.
+        F_a : `~astropy.units.Quantity`
+            Absorbed spectral flux density.
 
         """
 
     @abstractmethod
-    def emittance(self, e: u.physical.angle, phi: u.physical.angle) -> u.Quantity:
-        r"""Emission of light.
+    def emission(
+        self,
+        X_e: SpectralFluxDensityQuantity,
+        e: u.physical.angle,
+        phi: u.physical.angle,
+    ) -> u.Quantity:
+        r"""Emission of light from a surface, as seen by a distant observer.
 
         The surface is observed at an angle of :math:`e`, measured from the
         surface normal direction, and at a solar phase angle of :math:`phi`.
 
 
         Parameters
         ----------
+        X_e : `astropy.units.Quantity`
+            Emitted spectral radiance.
+
         e : `~astropy.units.Quantity`
-            Angle from normal of emitted light.
+            Observed angle from normal.
 
         phi : `~astropy.units.Quantity`
             Source-target-observer (phase) angle.
 
 
         Returns
         -------
-        e : `~astropy.units.Quantity`
-            Surface emittance.
+        F_e : `~astropy.units.Quantity`
+            Spectral flux density / spectral irradiance received by the
+            observer.
 
         """
 
@@ -96,36 +112,6 @@ def reflectance(
         emitted light are assumed to be collimated.
 
 
-        Parameters
-        ----------
-        i : `~astropy.units.Quantity`
-            Angle from normal of incident light.
-
-        e : `~astropy.units.Quantity`
-            Angle from normal of emitted light.
-
-        phi : `~astropy.units.Quantity`
-            Source-target-observer (phase) angle.
-
-
-        Returns
-        -------
-        r : `~astropy.units.Quantity`
-            Surface reflectance.
-
-        """
-
-    @abstractmethod
-    def radiance(
-        self,
-        F_i: SpectralFluxDensityQuantity,
-        i: u.physical.angle,
-        e: u.physical.angle,
-        phi: u.physical.angle,
-    ) -> u.Quantity:
-        """Observed radiance from a surface.
-
-
         Parameters
         ----------
         F_i : `astropy.units.Quantity`
@@ -143,8 +129,8 @@ def radiance(
 
         Returns
         -------
-        radiance : `~astropy.units.Quantity`
-            Observed radiance.
+        F_r : `~astropy.units.Quantity`
+            Spectral flux density / spectral irradiance received by the observer.
 
         """
 
@@ -165,14 +151,14 @@ def _vectors_to_angles(
         return i, e, phi
 
     @u.quantity_input
-    def radiance_from_vectors(
+    def reflectance_from_vectors(
         self,
         F_i: SpectralFluxDensityQuantity,
         n: np.ndarray,
         rs: u.physical.length,
         ro: np.ndarray,
     ) -> u.Quantity:
-        """Observed radiance from a surface with geometry defined by vectors.
+        """Vector based alternative to reflectance().
 
         Input vectors do not need to be normalized.
 
@@ -194,9 +180,9 @@ def radiance_from_vectors(
 
         Returns
         -------
-        radiance : `~astropy.units.Quantity`
-            Observed radiance.
+        reflectance : `~astropy.units.Quantity`
+            Reflectance.
 
         """
 
-        return self.radiance(F_i, *self._vectors_to_angles(n, rs, ro))
+        return self.reflectance(F_i, *self._vectors_to_angles(n, rs, ro))