specman.design

Design notes for specman, the spectrum manipulation package
-----------------------------------------------------------

The fundamental object here is the SPECTRUM.  A spectrum is a mapping
between SPECTRAL COORDINATES (typically wavelengths, frequencies, energies,
or similar) and the corresponding SPECTRAL INTENSITY.  The spectral
intensity gives a measure of how much energy is emitted or detected
per unit spectral coordinate interval per unit area.

Spectra come in two (or more) flavors: Analytic functions (such as black body
functions, Gaussians, Lorentzians, power laws, etc) and Tables.  Typically,
the former are used to model spectra, and the latter are the result of an
observation.  The former type is continuous, and provides a method for
calculating the spectral intensity for any value of the spectral coordinate
using analytic functions, while the latter type is discrete, and so the
spectral intensity is only available for a limited set of spectral coordinates.
Converting from an analytic function to a table involves loss of information
(since the capability for calculating the spectral intensity for spectral
coordinates other than those in the table set is lost), while converting
from a table to an analytic function (for example, by interpolating) involves
guessing what the spectral intensity is at spectral coordinates other than
those provided.  This loss or distortion of information means that conversion
of spectra from one form to another should be done only when absolutely
necessary.

A spectrum has the following properties:

1)  It knows how to supply an array of spectral coordinates that is
    appropriate for itself.  For example, a tabular spectrum knows how to
    return the spectral coordinates it is specified at, and a Gaussian knows
    that it needs to supply a wavelength set centered around its center and
    with enough resolution to adequately represent its shape.
2)  It knows how to calculate the spectral intensity given an input array
    of spectral coordinates that is unrelated to the array from 1)
3)  Its spectral coordinates and spectral intensity both have units that
    default to the units that the spectrum was originally supplied with
4)  It has an internal representation that is calculated when the spectrum
    object is instantiated.  This representation is (angstroms, photlam).
5)  It can convert its internal representation to any other set of units

  A related object is the SPECTRAL ELEMENT.  This is used to represent
elements of an optical system, such as mirrors, lenses, filters and
detectors.  SpectralElements represent a mapping between spectral coordinates
and a dimensionless ratio of output to input intensity.  They share some of
the characteristics of Spectrum objects, and can be discrete (like most of
the throughput tables in the synphot system) or analytic (e.g. constant
transmission, gaussian, tophat,...).

  SpectralElements have the following properties:

1) They know how to supply a set of spectral coordinates that describe the
domain over which they can be calculated
2) They can calculate the dimensionless transmission given an array of
spectral coordinates that is unrelated to the set from 1)
3) They remember the units of the spectral coordinates they were instantiated
with
4) They have an internal representation that is the same for all
SpectralElements - (angstroms, unitless)
5) They can convert from the internal representation to their initial
representation

  So SpectralElements and Spectrum objects have very similar properties,
which allows much of the same machinery to be used without caring whether
the object is a Spectrum or a SpectralElement.

  It is in combining SpectralElements and Spectrum objects that the differences
emerge.  Combining such objects produces a Composite object subject to the
following rules:

1) A Spectrum may be added to another Spectrum returning a CompositeSpectrum
object
2) A SpectralElement may be multiplied by another SpectralElement resulting
in a CompositeSpectralElement object
3) A Spectrum may be multiplied by SpectralElement object resulting in a
CompositeSpectrum object

  In each case, the Spectrum or SpectralElement that is combined may be
Composite or simple.

  The Composite objects are references to the objects that it is composed of.
The actual calculation of the sum or product is not performed until the
__call__ method of the Composite object is called.  The __call__ method takes
as input the array of wavelengths at which the spectral intensity of the
Composite object is to be calculated.  Since this wavelength array  is
specified, the Composite object returns a TabularSpectrum (or
TabularSpectralElement), i.e. specified at a fixed number of wavelength
points. The wavelength set is calculated by forming the union of wavelengths
from each of the component Spectrum or SpectralElement objects.

  So processes involved in using the spectrum package are:

1) Instantiation

 - A Spectrum or SpectralElement object is instantiated either from an input
FITS table or an analytic function

 - The original units of the object are kept as attributes.  In the case of
a FITS table, the original units are read from the TUNIT1 (spectral coordinate)
and TUNIT2 (spectral intensity/throughput) FITS header parameters

 - The units of an analytic function are specified as parameters in the
constructor.  Technically, most analytic functions change their analytic
form when converted from one representation to another.  For example, a
Gaussian in (frequency, F-nu) space is not a Gaussian in (wavelength,
F-lambda) space.  We will deal with this by just calculating the equivalent
parameters in (angstroms, photlam) space and treating the analytic function
as a Gaussian in (angstroms, photlam) space.

 - If the Spectrum or SpectralElement is instantiated from a FITS table,
it is converted to the internal representation of (angstroms, photlam).

 - If the Spectrum or SpectralElement is instantiated from an analytic
function, the corresponding parameters of the analytic function are calculated
in (angstroms, photlam) space.


2) Doing stuff

 - Spectrum and/or SpectralElement objects are combined using the rules for
composition described above.

 - Methods are defined for performing common tasks on the
Spectrum/SpectralElement objects, for example, integrating over the wavelength
set of interest.

3) Getting at the answers

 - A Composite object is just a reference to the tree of component objects.  No
actual calculations have been done

 - The object is calculated at an array of wavelengths by giving the wavelength
array as an argument to the object (using the internal __call__ method).  A
Tabular object is returned, in the internal representation and with the
units of the dominant component.

 - The arrays of (spectral coordinate, spectral intensity) are retrieved by
calling methods to convert from the internal representation to the units of
the object.  1-d numarrays are returned.