.. _ForwardModel:

Forward Model
=============


All users of the instrument model API wishing to calculate radiance signals will create an instance of
:ref:`forwardmodel_class` as there interface to the radiative transfer engine.  The :ref:`forwardmodel_class`
requires a valid :ref:`instrument_class` object when it is created.

Other run-time initialization options allow,

    1. a callback function to automatically generate custom level 1 data structures when radiances are calculated.
    2. allow custom platforms to be used
    3. choose between UVIS-NIR or IR :ref:`radiancesimulator_class` objects'

The :ref:`forwardmodel_class` allows users to calculate radiance and to access the pixels within the instrument.


The instrument model uses a :ref:`radiancesimulator_class` to interface the model framework with the **sasktran** api
functions. Users will create an instance of this class either explicitly or implicitly when they create their
:ref:`forwardmodel_class` object but apart from that do not need access to any of the internals.

Users must ensure that they create a :ref:`radiancesimulator_class` object appropriate for their needs. They can use
the default :ref:`radiancesimulator_class` object for UVIS-NIR applications or they must explictly set
:ref:`radiancesimulator_ir_class` for IR applications.

Doug's Theory
------------
Consider an optical system as shown in the sytem below. The front aperture is observing light from extended distant objects
over an area :math:`A`. The incident radiance at a given solid angle, :math:`\Omega`, and wavelength, :math:`\lambda`, is given
by :math:`I(\lambda, \Omega)`, specified in :math:`photons/cm^2/sec/ster/nm`. The photon signal collected over a solid angle,
:math:`\Delta\Omega`, propagates through the optical system and is distributed across the surface of the focal plane array detector
with spatial dimensions :math:`x` and :math:`y`.

.. image:: figures/optics_schematic.png
     :scale: 30 %
     :alt: Optics overview

The incoming radiance, :math:`I(\lambda,\Omega)`, is incident upon the front aperture, propagates through the system and is
distributed across the focal plane array surface by the optical system as a photon density function,

..  math::

    P(\lambda,\Omega, x,y) =  A\,I(\lambda,\Omega)\,\tau(\lambda)\,f(\lambda, \Omega, x, y )

which is a continuous density function and has units :math:`\left[ photons\,sec^{-1}\,ster^{-1}\,nm^{-1}\,{\mu m}^{-2} \right]`: it
represents the number of photons from direction :math:`\Omega`, wavelength :math:`\lambda`, striking the detector surface at location :math:`(x,y)`. We have the following terms:

    #. :math:`A` is the area of the front-end aperture in :math:`cm^2`.
    #. :math:`I(\lambda,\Omega)` is the incoming radiance in direction :math:`\Omega`, wavelength :math:`\lambda`
    #. :math:`\tau(\lambda)` is an explicit, unit-less term that reflects the optical transmission of the optics. It can be folded into function :math:`f` if desired.
    #. :math:`f(\lambda, \Omega, x, y )` is a function that describes how signal from incoming
      direction :math:`\Omega` and wavelength :math:`\lambda` is distributed across the detector surface. It is given in units of :math:`{\mu m}^{-2}`

The distribution, :math:`f(\lambda, \Omega, x, y )`, is typically more complicated than a simple one-to-one mapping as it accounts for the
special physical properties of the optical systems we are trying to model. These systems typically include diffraction and interference. For example,

    * a diffraction grating system (e.g. CATS, OSIRIS) images different wavelengths to different parts of the detector surface in one dimension.
    * a spatial heterodyne system (e.g. SHOW) or Fourier transform spectrometer (e.g. LIFE) will distribute all incoming wavelengths across the entire detector surface in one direction.
    * an imaging system (e.g. ALI) will, to first order, image the incomining solid angle to a corresponding area on the detector although chromatic aberrations may change this in second order.

The total photon signal, :math:`S`, incident upon an area, :math:`a`, is given by

..  math::

    S(a) = \int_{\Omega}\int_{\lambda}\int_{x_0}^{x_f}\int_{y_0}^{y_f} P(\lambda,\Omega, x,y) \,d\Omega\,d\lambda\,dx\,dy

which upon substitution for :math:`P` from above becomes

..  math::

    S(a) = A\,\int_{\Omega}\int_{\lambda}\,I(\lambda,\Omega)\,\tau(\lambda)\, \left[\int_{x_0}^{x_f}\int_{y_0}^{y_f} f(\lambda,\Omega, x,y) \,dx\,dy\right]\,d\Omega\,d\lambda

or

..  math::

    S(a) = A\,\int_{\Omega}\int_{\lambda} I(\lambda,\Omega)\,\tau(\lambda)\,f^\prime(\lambda,\Omega, a) \,d\Omega\,d\lambda

where

..  math::

   f^\prime(\lambda,\Omega, a) = \int_{x_0}^{x_f}\int_{y_0}^{y_f} f(\lambda,\Omega, x,y) \,dx\,dy

In this latter notation we see that :math:`f^\prime(\lambda,\Omega, a)` acts like a point spread function for the
macroscopic area, :math:`a`, as it describes the contribution of each radiance at the front aperture to the total
signal on the detector surface.