% Time-stamp: <98/05/29 16:16:03 dph> 
% MIT Directory: ~dph/h1/ASC/TG/Flight/Development/Expmap/Doc
% File: expmap_arf.txt
% Author: D. Huenemoerder
% Original version: 980225
%
% (this header is ~dph/libidl/time-stamp-template.el)
% to auto-update the stamp in emacs, put this in your .emacs file:
%      (add-hook 'write-file-hooks 'time-stamp)
%====================================================================

		  Exposure map prototype interface:

exp_make_map

  Calculate the imaging-mode response (effective exposure time in
  units of [cm^2 s] ) as a function of energy and position by applying
  the observatory aspect solution to instrument response and geometry
  (the instrument map, see below). The fundamental output is a 2D
  image, with two spatial dimensions (the sky X,Y --- R.A. and Dec
  tangent-plane with respect to the nominal pointing). Optionally, if
  the instrument map is 3-dimensional (two spatial and one energy
  dimensions), the output will be a 3D-map.

  Pipeline products will be 2D, for pre-defined instrument maps. User
  analysis may specify 3D input/output.


  Parameters control the spatial and spectral resolution.
  

  This is the basic exposure map engine.  Other tools (to be
  specified) will call this and process output into higher level
  response products, for example, narrow-band flat-fields, 
  source-region ARFs, or integrated over a spectral region w/
  spectral model weighting.


  Basic Parameters:

	Aspect solution (FITS bintable) 
	Good Time Interval (GTI; event-file extension reference)
        Sky Region  (bounding rectangle: min R.A., max R.A., min Dec,
                     max Dec)
	Sky Resolution in R.A. (R.A. arcsec/bin, Dec. arcsec/bin)

	Detector element


  Required calibration data:

        Instrument Map (see below)
	Detector geometry (pixlib params)
	Focal length (pixlib param)

  Observational parameters:

	Dead-time factor


  Output:
        
	2D image (FITS bintable, with axes, R.A., Dec., (in
	tangent-plane offsets from nominal R.A. and Dec., degrees),
	for the specified detector element as mapped to the sky for
	the given aspect history.

	If the input instrument map was 3D, output will be 3D, where
	the 3rd dimension is the same as the input map (energy,
	usually).

	
Notes: 

      Sky Region and Sky Resolution must specify one or more bins.

      Each detector element is done separately (e.g., single CCD's of
      ACIS-I or ACIS-S).  Multiple elements (or observations) may be
      merged, if desired, with re-binning and mosaicing tools (TBS).


      The Instrument Map:

      The nature of the output map is determined by the input
      "Instrument Map".  This map is typically the product of the
      detector quantum efficiency as a function of position and energy
      and mirror effective area as a function of position (off-axis
      angle and azimuthal angle) and energy, for a specified relative
      orientation ("aim point"; the possible SIM motion of order 5
      arcsec during is ignored, since the vignetting variation is
      small on this scale).  The map should include static bad pixels
      and have any region masks applied (such as ACIS windows).  

      The map may be differential in energy (i.e., a single energy
      bin), or it may be integrated over energy and/or pulse-height.
      If integrated over energy, spectral weighting may be applied,
      since the map is formally dependent upon the source spectrum.

      Instrument Map creation is described in TBD.

      The "off the shelf" instrument maps must have the following
      applied before use for any observation is processed:

	- ACIS windows (FITS region) (L1 file reference)
	- Bad pixel lists (static)   (L1 file reference)

      For "geometric exposure time" (detector on or off, unit mirror
      efficiency), the instrument map should be a map of the detector
      geometry only (no efficiency factor, except 1 or 0), and the
      resultant exposure map is unweighted integration time per sky
      pixel. 


      Timing:
	
	High resolution maps may be expensive to compute.  Care should
	be taken when specifying the sky output bin sizes, or number
	of energy bins to compute.

        Some timing benchmarks are: TBS

   	N_x  N_y   N_t   resolution   execution_time    platform
     
							Sun Ultra 2
							Pentium tbd
							TBD       
 


      Theory:

	For a theoretical description, see:

        For usage scenarios, see: