Index: trunk/psLib/src/math/psMinimize.h
===================================================================
--- trunk/psLib/src/math/psMinimize.h	(revision 1441)
+++ trunk/psLib/src/math/psMinimize.h	(revision 1468)
@@ -15,43 +15,85 @@
  */
 
-/** This routine must minimize a non-linear function */
-psVector* psMinimize(psVector* restrict initialGuess,
-                     float (*myFunction) (const psVector* restrict, const psVector* restrict),
-                     float (*myFunctionDeriv) (const psVector* restrict, const psVector* restrict, int),
-                     const psVector* restrict coord, const psVector* restrict paramMask);
+/** function of a collection of parameters and coordinate vector.
+ *
+ *  @return float    value to minimize
+ */
+typedef float (*psMinimizeFunction)(
+    const psVector* restrict params,   ///< collection of parameters
+    const psVector* restrict coord     ///< coordinates
+);
 
-/** Minimize chi^2 for input data */
-psVector* psMinimizeChi2(float (*evalModel) (const psVector* restrict, const psVector* restrict),     ///<
-                         // Model
-                         // to
-                         // fit;
-                         // (domain
-                         // and
-                         // params)
-                         float (*DevalModel) (const psVector* restrict, const psVector* restrict, int),       ///<
-                         // Derivative
-                         // of
-                         // model
-                         // to
-                         // fit;
-                         // (domain
-                         // and
-                         // params)
-                         const psImage* restrict domain,       ///< The domain values for the corresponding
-                         // measurements
-                         const psVector* restrict data,        ///< Data to fit
-                         const psVector* restrict errors,      ///< Errors in the data
-                         psVector* restrict initialGuess,      ///< Initial guess
-                         const psVector* restrict paramMask,   ///< 1 = fit for parameter, 0 = hold
-                         // parameter constant
-                         float *chiSq);
+typedef float (*psMinimizeFunctionDeriv) (
+    const psVector* restrict params,   ///< collection of parameters
+    const psVector* restrict coord,    ///< coordinates
+    int derivParam                     ///< index of parameter to calculate derivative of
+);
 
-/** Derive a polynomial fit by chi^2 minimisation (analytically) */
-psPolynomial1D* psVectorFitPolynomial1D(psPolynomial1D* myPoly,        ///< Polynomial to fit
-                                        const psVector* restrict x,    ///< Ordinates (or NULL to just use
-                                        // the indices)
-                                        const psVector* restrict y,    ///< Coordinates
-                                        const psVector* restrict yErr  ///< Errors in coordinates, or NULL
-                                       );
+/** Minimizes a non-linear function.
+ *
+ *  psMinimize determines and returns the vector that minimizes the specified 
+ *  function. It takes as input a function, myFunction, an initial guess for
+ *  the vector that minimizes the function, initialGuess, the current 
+ *  coordiate coord, and an optional mask for the vector elements (function 
+ *  parameters) to minimize, paramMask (all parameters are fit if PSLib SDRS 
+ *  25 July 13, 2004 Pan-STARRS Image Processing Pipeline PSDC-430-007-04 
+ *  NULL). Note that paramMask must be of type psU8, while params must be of 
+ *  type psF32. The optional function, myFuncDeriv returns the derivative of 
+ *  the function. This function must be valid only for types psF32, psF64.
+ *
+ *  @return psVector*    minimized vector
+ */
+psVector* psMinimize(
+    psVector* restrict initialGuess,
+    psMinimizeFunction myFunction,
+    psMinimizeFunctionDeriv myFunctionDeriv,
+    const psVector* restrict coord,
+    const psVector* restrict paramMask
+);
+
+/** Minimize chi^2 for input data.
+ *
+ *  psMinimizeChi2 fits a model to observations by minimizing chi^2, returning 
+ *  the best-fit parameters. The input parameters are a function that 
+ *  evaluates the model for a specified domain, given the parameters, 
+ *  evalModel; a list of observations, (domain, data, and errors); an initial 
+ *  guess at the best-fit parameters, initialGuess which is returned with the 
+ *  best-fit parameters, and an optional mask specifying which parameters are 
+ *  to be fit, paramMask, which must be of type psU8. All parameters are fit 
+ *  if this vector is NULL. This function must be valid only for types psF32, 
+ *  psF64.
+ *
+ *  @return psVector*      minimized vector
+ */
+psVector* psMinimizeChi2(
+    psMinimizeFunction evalModel,      ///< Model to fit; (domain and params)
+    psMinimizeFunctionDeriv DevalModel,///< Derivative of model to fit; (domain and params)
+    const psImage* restrict domain,    ///< The domain values for the corresponding measurements
+    const psVector* restrict data,     ///< Data to fit
+    const psVector* restrict errors,   ///< Errors in the data
+    psVector* restrict initialGuess,   ///< Initial guess
+    const psVector* restrict paramMask,///< 1 = fit for parameter, 0 = hold parameter constant
+    float *chiSq                       ///< chi squared
+);
+
+/** Derive a polynomial fit by chi^2 minimisation (analytically)
+ *
+ *  psVectorFitPolynomial1d returns the polynomial that best fits the 
+ *  observations. The input parameters are a polynomial that specifies the 
+ *  fit order, myPoly, which will be altered and returned with the best-fit 
+ *  coefficients; and the observations, x, y and yErr. The independent 
+ *  variable list, x may be NULL, in which case the vector index is used. 
+ *  The dependent variable error, yErr may be null, in which case the solution 
+ *  is determined in the assumption that all data errors are equal. This 
+ *  function must be valid only for types psF32, psF64.
+ *
+ *  @return psPolynomial1D*    polynomial fit
+ */
+psPolynomial1D* psVectorFitPolynomial1D(
+    psPolynomial1D* myPoly,            ///< Polynomial to fit
+    const psVector* restrict x,        ///< Ordinates (or NULL to just use the indices)
+    const psVector* restrict y,        ///< Coordinates
+    const psVector* restrict yErr      ///< Errors in coordinates, or NULL
+);
 
 /* \} */// End of MathGroup Functions