Index: trunk/psLib/src/dataManip/psMinimize.h =================================================================== --- trunk/psLib/src/dataManip/psMinimize.h (revision 4243) +++ trunk/psLib/src/dataManip/psMinimize.h (revision 4282) @@ -8,6 +8,6 @@ * @author GLG, MHPCC * - * @version $Revision: 1.44 $ $Name: not supported by cvs2svn $ - * @date $Date: 2005-06-14 02:54:12 $ + * @version $Revision: 1.45 $ $Name: not supported by cvs2svn $ + * @date $Date: 2005-06-16 02:50:59 $ * * Copyright 2004-2005 Maui High Performance Computing Center, University of Hawaii @@ -37,5 +37,5 @@ #include "psConstants.h" -/** A psMinimization data structure. +/** A data structure for minimization routines. * * Contains numerical analysis parameters/values @@ -82,6 +82,6 @@ /** Derive a one-dimensional spline fit. * - * Given a psSpline1D data structure and a set of x,y vectors, this routine generates - * the linear splines which satisfy those data points. + * Given a psSpline1D data structure and a set of x,y vectors, this routine + * generates the linear splines which satisfy those data points. * * @return psSpline1D*: the calculated one-dimensional splines @@ -94,8 +94,9 @@ ); -/** Defines a Levenberg-Marquardt function of a collection of parameters evaluated at a given position. - * - * @return psF64: a single floating-point value which is the value of the function given the parameters - * and coordinate vectors, along with the derivatives of the function with respect to each of the parameters. +/** Specifies the format of a user-defined function that the general Levenberg- + * Marquardt minimizer routine will accept. + * + * @return psF64: the single float value of the function given the parameters, + * positions, and derivatives. */ typedef @@ -106,129 +107,123 @@ ); -/** Fits a specified function based on the Levenberg-Marquardt method. - * - * @return psBool: True unless an error occurred. +/** Minimizes a specified function based on the Levenberg-Marquardt method. + * + * @return psBool: True if successful. */ psBool psMinimizeLMChi2( - psMinimization *min, ///< - psImage *covar, ///< - psVector *params, ///< - const psVector *paramMask, ///< - const psArray *x, ///< - const psVector *y, ///< - const psVector *yErr, ///< - psMinimizeLMChi2Func func ///< -); - -/** - * - * - * @return psBool: True if + psMinimization *min, ///< Minimization specification + psImage *covar, ///< Covariance matrix + psVector *params, ///< "Best Guess" for the parameters that minimize func + const psVector *paramMask, ///< Parameters to be held fixed by the minimizer + const psArray *x, ///< Measurement ordinates of multiple vectors + const psVector *y, ///< Measurement coordinates + const psVector *yErr, ///< Errors in the measurement coordinates + psMinimizeLMChi2Func func ///< Specified function +); + +/** Use specified alpha, beta, params to generate a new guess for Alpha, Beta, Params + * + * @return psBool: True if successful. */ psBool p_psMinLM_GuessABP( - psImage *Alpha, ///< - psVector *Beta, ///< - psVector *Params, ///< - psImage *alpha, ///< - psVector *beta, ///< - psVector *params, ///< - psF64 lambda ///< -); - -/** - * - * - * @return psF64: + psImage *Alpha, ///< New Alpha guess + psVector *Beta, ///< New Beta guess + psVector *Params, ///< New Params guess + psImage *alpha, ///< Old Alpha guess + psVector *beta, ///< Old Beta guess + psVector *params, ///< Old Params guess + psF64 lambda ///< Factor used in update //XXX Got Better Desc? +); + +/** Function used to set parameters for generating "best guess" in minimizing Chi-Squared value. + * + * @return psF64: Chi-squared value for new guess */ psF64 p_psMinLM_SetABX ( - psImage *alpha, ///< - psVector *beta, ///< - psVector *params, ///< - const psArray *x, ///< - const psVector *y, ///< - const psVector *dy, ///< - psMinimizeLMChi2Func func); ///< - -/** - * - * - * @return psF32: + psImage *alpha, ///< alpha guess + psVector *beta, ///< beta guess + psVector *params, ///< params guess + const psArray *x, ///< Measurement ordinates + const psVector *y, ///< Measurement coordinates + const psVector *dy, ///< Weights calculated from y-errors + psMinimizeLMChi2Func func); ///< Specified function + +/** Specifies the format of a user-defined function that the general Powell + * minimizer routine will accept. + * + * @return psF32: the single float value of the function given the parameters + * and coordinate vectors. */ typedef psF32 (*psMinimizePowellFunc)( - const psVector *params, ///< - const psArray *coords ///< -); - - -/** - * + const psVector *params, ///< Parameters used to evaluate the function + const psArray *coords ///< Coordinates at which to evaluate +); + +/** Minimizes a specified function based on the Powell method. + * + * @return psBool: True if successful. + */ +psBool psMinimizePowell( + psMinimization *min, ///< Minimization specification + psVector *params, ///< "Best guess" for parameters that minimize func + const psVector *paramMask, ///< Parameters to be held fixed by minimizer + const psArray *coords, ///< Measurement coordinates + psMinimizePowellFunc func ///< Specified function +); + +/** Calculates the one-dimensional Gaussian in a format acceptable to the Levenberg- + * Marquardt minimizer routine. * - * @return psBool: True if - */ -psBool psMinimizePowell( - psMinimization *min, ///< - psVector *params, ///< - const psVector *paramMask, ///< - const psArray *coords, ///< - psMinimizePowellFunc func ///< -); - -/** - * - * - * @return psVector*: + * @return psVector*: Calculated values */ psVector *psMinimizeLMChi2Gauss1D( - psImage *deriv, ///< - const psVector *params, ///< - const psArray *coords ///< -); - -/** - * - * - * @return psVector*: + psImage *deriv, ///< Derivative Matrix + const psVector *params, ///< Parameters used in evaluation + const psArray *coords ///< Measurement coordinates +); + +/** Calculates the one-dimensional Gaussian in a format acceptable to the Powell + * chi-squared minimizer routine. + * + * @return psVector*: Calculated values */ psVector *psMinimizePowellChi2Gauss1D( - const psVector *params, ///< - const psArray *coords ///< -); - -/** - * - * - * + const psVector *params, ///< Parameters used in evaluation + const psArray *coords ///< Measurement coordinates +); + +/** Specifies the format of a user-defined function that the general Powell chi- + * squared minimizer routine will accept. + * + * @return psVector*: Calculated values given the parameters and coordinates. */ typedef psVector *(*psMinimizeChi2PowellFunc)( - const psVector *params, ///< - const psArray *coords ///< -); - - -/** - * + const psVector *params, ///< Parameters used to evaluate the function + const psArray *coords ///< Coordinates at which to evaluate +); + +/** Minimizes a specified function based on the Powell chi-squared method. * - * @return psBool: True if + * @return psBool: True is successful. */ psBool psMinimizeChi2Powell( - psMinimization *min, ///< - psVector *params, ///< - const psVector *paramMask, ///< - const psArray *coords, ///< - const psVector *value, ///< - const psVector *error, ///< - psMinimizeChi2PowellFunc func ///< -); - -/** - * - * - * @return bool: True if + psMinimization *min, ///< Minimization specification + psVector *params, ///< "Best guess" for parameters that minimize func + const psVector *paramMask, ///< Parameters to be held fixed by minimizer + const psArray *coords, ///< Measurement coordinates + const psVector *value, ///< Measured values at the coordinates + const psVector *error, ///< Errors in the measure values (or NULL) + psMinimizeChi2PowellFunc func ///< Specified function +); + +/** Gauss-Jordan numerical solver. + * + * @return bool: True if successful. */ bool psGaussJordan( - psImage *a, ///< - psVector *b ///< + psImage *a, ///< Matrix to be solved + psVector *b ///< Vector of values );