You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/sbpy/surfaces.rst
+121-6Lines changed: 121 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,7 +3,6 @@ Surfaces Module (`sbpy.surfaces`)
3
3
4
4
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.
5
5
6
-
7
6
.. figure:: ../static/scattering-vectors.svg
8
7
:alt:Diagram of surface scattering and emission vectors
9
8
@@ -17,15 +16,13 @@ Surfaces are expected to require albedo and/or emissivity. Conventions on which
17
16
Built-in surface models
18
17
-----------------------
19
18
20
-
The model `sbpy.surfaces.scattered.LambertianSurfaceScatteredSunlight` is used to observe sunlight scattered from a Lambertian surface (light scattered uniformly in all directions).
21
-
22
-
Create an instance of the ``LambertianSurfaceScatteredSunlight`` model, and calculate the absorptance, emittance, and reflectance for :math:`(i, e, \phi) = (30^\circ, 60^\circ, 90^\circ)`.
19
+
The model `~sbpy.surfaces.scattered.LambertianSurfaceScatteredSunlight` is used to observe sunlight scattered from a Lambertian surface (light scattered uniformly in all directions).
23
20
24
-
.. code:: python
21
+
Create an instance of the ``LambertianSurfaceScatteredSunlight`` model, and calculate the absorptance, emittance, and reflectance for :math:`(i, e, \phi) = (30^\circ, 60^\circ, 90^\circ)`::
@@ -38,5 +35,123 @@ Create an instance of the ``LambertianSurfaceScatteredSunlight`` model, and calc
38
35
<Quantity [0.04330127]>
39
36
40
37
38
+
Radiance of scattered/emitted light
39
+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
40
+
41
+
All `~sbpy.surfaces.surface.Surface` models have a :meth:`~sbpy.surfaces.surface.Surface.radiance` method that calculates the radiance of scattered/emitted light, given the spectral flux density of incident light at the surface::
>>> surface.radiance(F_i, i, e, phi) # doctest: +FLOAT_CMP
45
+
<Quantity [43.30127019] W / (sr um m2)>
46
+
47
+
48
+
Radiance of scattered sunlight
49
+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
50
+
51
+
``LambertianSurfaceScatteredSunlight`` is derived from the ``ScatteredSunlight`` class, which provides convenience methods for calculating the radiance of sunlight scattered off the surface::
52
+
53
+
>>> wave = 0.55 * u.um
54
+
>>> rh = 1 * u.au # heliocentric distance of the surface
55
+
>>> surface.scattered_sunlight(wave, rh, i, e, phi) # doctest: +FLOAT_CMP
56
+
<Quantity [81.34078653] W / (sr um m2)>
57
+
58
+
The solar spectrum is configured using Sbpy's calibration system. See :doc:`calib` for details.
59
+
60
+
61
+
Radiance from vectors
62
+
^^^^^^^^^^^^^^^^^^^^^
63
+
64
+
As an alternative to using :math:`(i, e, \phi)`, radiance may be calculated using vectors that define the normal direction, radial vector of the light source, and radial vector of the observer::
65
+
66
+
>>> # the following vectors are equivalent to (i, e, phi) = (30, 60, 90) deg
67
+
>>> n = [1, 0, 0]
68
+
>>> rs = [0.866, 0.5, 0] * u.au
69
+
>>> ro = [0.5, -0.866, 0] * u.au
70
+
>>>
71
+
>>> surface.radiance_from_vectors(F_i, n, rs, ro) # doctest: +FLOAT_CMP
72
+
<Quantity [43.30190528] W / (sr um m2)>
73
+
>>> surface.scattered_sunlight_from_vectors(wave, n, rs, ro) # doctest: +FLOAT_CMP
74
+
<Quantity [81.34555875] W / (sr um m2)>
75
+
76
+
Notice that heliocentric distance was not needed in the call to ``scattered_sunlight_from_vectors`` because it was already accounted for by the ``rs`` vector.
77
+
78
+
41
79
Building your own surface models
42
80
--------------------------------
81
+
82
+
Defining your own surface model is typically done by creating a new class based on `~sbpy.surfaces.surface.Surface`, and defining methods for ``absorptance``, ``emittance``, and ``reflectance``. The `~sbpy.surfaces.lambertian.Lambertian` model serves as a good example. For surface scattering problems, most users will combine their class with the `~sbpy.surfaces.scattered.ScatteredLight` or `~sbpy.surfaces.scattered.ScatteredSunlight` classes, which provide the ``radiance`` method to complete the ``Surface`` model.
83
+
84
+
Here, we define a new surface model with surface scattering proportional to :math:`\cos^2` based on the `~sbpy.surfaces.scattered.ScatteredSunlight` class::
85
+
86
+
>>> import numpy as np
87
+
>>> from sbpy.surfaces import Surface, ScatteredSunlight
88
+
>>>
89
+
>>> class Cos2SurfaceScatteredSunlight(ScatteredSunlight):
90
+
... """Absorption and scattering proportional to cos**2."""
>>> surface.reflectance(i, e, phi) # doctest: +FLOAT_CMP
103
+
<Quantity [0.01875]>
104
+
>>> surface.radiance(F_i, i, e, phi) # doctest: +FLOAT_CMP
105
+
<Quantity [18.75] W / (sr um m2)>
106
+
>>> surface.scattered_sunlight(wave, rh, i, e, phi) # doctest: +FLOAT_CMP
107
+
<Quantity [35.22159375] W / (sr um m2)>
108
+
109
+
However, if a scattering model will be re-used with other classes, e.g., for scattered light and thermal emission modeling, then the most flexible approach is to base the model on ``Surface`` and have derived classes combine the model with scattering or thermal emission classes::
110
+
111
+
>>> class Cos2Surface(Surface):
112
+
... """Abstract base class for absorption and scattering proportional to cos**2.
113
+
...
114
+
... We document this as an "abstract base class" because the ``radiance``
115
+
... method required by ``Surface`` is not implemented here, and therefore
116
+
... this class cannot be used directly (i.e., it cannot be instantiated).
>>> class Cos2SurfaceScatteredSunlightAlt(Cos2Surface, ScatteredSunlight):
130
+
... """Absorption and scattering proportional to cos**2.
131
+
...
132
+
... This class combines the ``absorptance``, ``emittance``, and ``reflectance``
133
+
... methods from ``Cos2Surface`` with the ``radiance`` and ``scattered_sunlight``
134
+
... methods of ``ScatteredSunlight``.
135
+
...
136
+
... Parameters
137
+
... ...
138
+
... """
139
+
>>>
140
+
>>> class Cos2SurfaceThermalEmission(Cos2Surface, ThermalEmission): # doctest: +SKIP
141
+
... """Absorption and thermal emission proportional to cos**2.
142
+
...
143
+
... This class combines the ``absorptance``, ``emittance``, and ``reflectance``
144
+
... from ``Cos2Surface`` with the ``radiance`` method of a fictitious
145
+
... ``ThermalEmission`` class.
146
+
...
147
+
... Parameters
148
+
... ...
149
+
... """
150
+
151
+
Thanks to their base classes (``Cos2Surface``, ``ScatteredSunlight``, and ``ThermalEmission``), the ``Cos2SurfaceScatteredSunlightAlt`` and ``Cos2SurfaceThermalEmission`` classes are complete and no additional code is needed, just documentation.
0 commit comments