include	<tbset.h>
include "polarimetry.h"

#  POLARIMETRY -- Compute indices of polarization from HSP measurements
#
#  Description:
#  ------------
#  The amount and angle of linear polarization are computed from measurements
#  through four Polaroid filters.  Normalized Stokes parameters are also 
#  calculated.
#  
#  The HSP aperture assembly contains four near ultraviolet filters.  Each 
#  filter has four apertures with polarizers oriented at 0, 45, 90, and 135 
#  degrees.  Linear polarization in any filter is measured by observing through #  each of the four apertures The measurements through each aperture are
#  supposedly already corrected for instrumental polarization (i.e. relative
#  sensitivity) prior to the data reduction of this task.  
#  
#  The normalized Stokes parameters I, q and u are computed from the four
#  measurements and are transformed from the instrumental coordinate system 
#  to the equatorial coordinate system.  Then, the degree of linear polarization
#  and its position angle are calculated from the normalized Stokes parameters.
#
#  During the data reduction, measurements are corrected for polarization 
#  efficiency and position angle offset which are stored in the calibration 
#  database and are maintained by STScI. The user of this task may substitute 
#  different correction factors during the reduction procedurea by giving these
#  values in the user parameters.
#  
#  The input data for this procedure are four time series files, one for each of
#  the apertures for the chosen wavelength filter.  All four time series files
#  must contain the same number of measurements.  
#  
#  Each of the four time series files may be associated with a data mask file.  
#  If any of the four measurements in a given pixel is flagged as bad pixel in 
#  the data mask file, no calculations of polarization indices are performed for
#  that pixel.  The pixels in the output time series of polarization indices 
#  are filled with DATAFILL.  
#
#  Date		Author			Description
#  ----		------			-----------
#  06-Sep-1984  M. F. Hartman		original code
#  19-Jun-1990  J.-C. Hsu		rewrite in SPP
#------------------------------------------------------------------------------

procedure polarimetry ()

pointer	fin, finmask, fout
			# file template pointers
int	nsets		# sets of input files 
bool	mask		# are there input mask files?
pointer	tp_poleff, tp_paoffset
			# table pointers
int	npts_poleff, npts_paoffset
			# sizes of the tables
pointer	aper_poleff 	# tabulated aperture names
pointer	poleff, poleff_err
			# tabulated polarization efficiencies and errors
pointer	filter_pa 	# tabulated filter names
pointer	paoffset, paoffset_err
			# tabulated position angle offsets and errors
real	peff[NAPER], peff_err[NAPER]
			# polarization efficiencies and errors
real	pa0, pa0_err	# position angle offset and error
real	datafill	# fill value for the invalid pixels in the 
			# output data file
pointer	sp

int	tbpsta()
#==============================================================================
begin

	# announce start of the task
	call printf ("*** POLARIMETRY - Version 1.0 ***\n")

	# get input parameters
	call pol_get (fin, finmask, fout, nsets, mask, tp_poleff, tp_paoffset,
			peff, pa0, datafill)

	call smark (sp)

	# read the polarization efficiency table if it is supplied
	if (tp_poleff != NULL) {
	    npts_poleff = tbpsta (tp_poleff, TBL_NROWS)
	    if (npts_poleff <= 0)
		call error (1, "empty polarization efficiency table")
	    call salloc (aper_poleff, (SZ_APER+1)*npts_poleff, TY_CHAR)
	    call salloc (poleff, npts_poleff, TY_REAL)
	    call salloc (poleff_err, npts_poleff, TY_REAL)
	    call read_poleff (tp_poleff, Memc[aper_poleff], Memr[poleff], 
				Memr[poleff_err], npts_poleff)
	} else {
	    
	    # allocate the place holder
	    npts_poleff = NULL 
	    call salloc (aper_poleff, 1, TY_CHAR)
	    call salloc (poleff, 1, TY_REAL)
	    call salloc (poleff_err, 1, TY_REAL)
	    call tbtclo (tp_poleff)
	}

	# ditto for the position angle table
	if (tp_paoffset != NULL) {
	    npts_paoffset = tbpsta (tp_paoffset, TBL_NROWS)
	    if (npts_paoffset <= 0)
		call error (1, "empty position angle offset table")
	    call salloc (filter_pa, (SZ_FILTER+1)*npts_paoffset, TY_CHAR)
	    call salloc (paoffset, npts_paoffset, TY_REAL)
	    call salloc (paoffset_err, npts_paoffset, TY_REAL)
	    call read_paoffset (tp_paoffset, Memc[filter_pa], Memr[paoffset], 
				Memr[paoffset_err], npts_paoffset)
	} else {
	    
	    # allocate the place holder
	    npts_paoffset = NULL
	    call salloc (filter_pa, 1, TY_CHAR)
	    call salloc (paoffset, 1, TY_REAL)
	    call salloc (paoffset_err, 1, TY_REAL)
	    call tbtclo (tp_paoffset)
	}

	# do the polarization calculation
	call pol_do (fin, finmask, fout, nsets, mask, 
			npts_poleff, npts_paoffset, Memc[aper_poleff], 
			Memr[poleff], Memr[poleff_err], Memc[filter_pa], 
			Memr[paoffset], Memr[paoffset_err], 
			peff, pa0, peff_err, pa0_err, datafill)

	call sfree (sp)

	# close file templates
	call imtclose (fin)
	call imtclose (finmask)
	call imtclose (fout)

	# announce completion of task
	call printf ("polarimetry reduction task completed with no error\n")
end