/** @file  pmPSFtry.h
 *
 * This file contains code that allows the user to try to fit several
 * PSF models to an image.
 *
 *  @author EAM, IfA
 *
 *  @version $Revision: 1.3.4.1 $ $Name: not supported by cvs2svn $
 *  @date $Date: 2006-02-17 17:13:42 $
 *
 *  Copyright 2004 Maui High Performance Computing Center, University of Hawaii
 *
 */

# ifndef PM_PSF_TRY_H
# define PM_PSF_TRY_H


/**
 * 
 * This structure contains a pointer to the collection of sources which will
 * be used to test the PSF model form. It lists the pmModelType type of model
 * being tests, and contains an element to store the resulting psf
 * representation. In addition, this structure carries the complete collection of
 * EXT (floating parameter) and PSF (fixed parameter) model fits to each of the
 * sources modelEXT and modelPSF. It also contains a mask which is set by the
 * model fitting and psf fitting steps. For each model, the value of the quality
 * metric is stored in the vector metric and the fitted instrumental magnitude is
 * stored in fitMag. The quality metric for the PSF model is the aperture
 * magnitude minus the fitted magnitude for each source. This collection of
 * aperture residuals is examined in the analysis process, and a linear trend of
 * the residual with the inverse object flux (ie, 100:4his structure contains a
 * pointer to the collection of sources which will be used to test the PSF model
 * form. It lists the pmModelType type of modmag) is fitted. The result of this
 * fit is a measured sky bias (systematic error in the sky measured by the fits),
 * an effective infinite-magnitude aperture correction (ApResid), and the scatter
 * of the aperture correction for the ensemble of PSF stars (dApResid). The
 * ultimate metric to intercompare multiple types of PSF models is the value of
 * the aperture correction scatter.
 * 
 * XXX: There are many more members in the SDRS then in the prototype code.
 * I stuck with the prototype code.
 * 
 * 
 */
typedef struct
{
    pmPSF      *psf;                    ///< Add comment.
    psArray    *sources;                ///< pointers to the original sources
    psArray    *modelEXT;               ///< model fits, floating parameters
    psArray    *modelPSF;               ///< model fits, PSF parameters
    psVector   *mask;                   ///< Add comment.
    psVector   *metric;                 ///< Add comment.
    psVector   *fitMag;                 ///< Add comment.
}
pmPSFtry;


/** pmPSFtryMaskValues
 * 
 * The following datatype defines the masks used by the pmPSFtry analysis to
 * identify sources which should or should not be included in the analysis.
 * 
 */
typedef enum {
    PSFTRY_MASK_CLEAR    = 0x00,        ///< Add comment.
    PSFTRY_MASK_OUTLIER  = 0x01,        ///< 1: outlier in psf polynomial fit (provided by psPolynomials)
    PSFTRY_MASK_EXT_FAIL = 0x02,        ///< 2: ext model failed to converge
    PSFTRY_MASK_PSF_FAIL = 0x04,        ///< 3: psf model failed to converge
    PSFTRY_MASK_BAD_PHOT = 0x08,        ///< 4: invalid source photometry
    PSFTRY_MASK_ALL      = 0x0f,        ///< Add comment.
} pmPSFtryMaskValues;


/** pmPSFtryAlloc()
 * 
 * Allocate a pmPSFtry data structure.
 * 
 */
pmPSFtry *pmPSFtryAlloc(
    psArray *stars,                     ///< Add comment.
    char *modelName                     ///< Add comment.
);


/** pmPSFtryModel()
 * 
 * This function takes the input collection of sources and performs a complete
 * analysis to determine a PSF model of the given type (specified by model name).
 * The result is a pmPSFtry with the results of the analysis.
 * 
 */
pmPSFtry *pmPSFtryModel(
    psArray *sources,                   ///< Add comment.
    char *modelName,                    ///< Add comment.
    float radius                        ///< Add comment.
);


/** pmPSFtryMetric()
 * 
 * This function is used to measure the PSF model metric for the set of
 * results contained in the pmPSFtry structure.
 * 
 */
bool pmPSFtryMetric(
    pmPSFtry *psfTry,                  ///< Add comment.
    float RADIUS                       ///< Add comment.
);

/** pmPSFtryMetric_Alt()
 *
 * This function is used to measure the PSF model metric for the set of
 * results contained in the pmPSFtry structure (alternative implementation).
 *
 */
bool pmPSFtryMetric_Alt(
    pmPSFtry *try
    ,                      ///< Add comment.
    float RADIUS                        ///< Add comment.
);

# endif
