home *** CD-ROM | disk | FTP | other *** search
/ vis-ftp.cs.umass.edu / vis-ftp.cs.umass.edu.tar / vis-ftp.cs.umass.edu / pub / Software / ASCENDER / ascendMar8.tar / UMass / Triangulate / include / marquardt.h < prev    next >
C/C++ Source or Header  |  1995-04-13  |  5KB  |  151 lines
  1. /* @(#)marquardt.h    1.2 6/2/93 */
  2. /* Structures for controlling the Marquardt algorithm */
  3.  
  4. #ifndef marquardt_h
  5. #define marquardt_h
  6.  
  7. #include "cvar.h"
  8.  
  9. typedef struct
  10.    {
  11.    /* Parameters controlling the flow of the problem */
  12.    int     Num_Loops;    /* Maximum number of iterations */
  13.    double Min_Incr;      /* Square of smallest significant parameter change */
  14.    int diag;        /* 1 means weight matrix is diagonal, 0 = square */
  15.  
  16.    /* The size of the problem */
  17.    int nrows, ncols;    /* Size of the problem (Jacobian dimensions) */
  18.  
  19.    /* Input and output */
  20.    double **weight;    /* Input covariance weight matrix */
  21.    double **covar;    /* Output covariance matrix */
  22.    double *param;    /* Array of pointers to parameter values */
  23.    double *goal;        /* Goal vector */
  24.  
  25.    /* Functions */
  26.    FUNCTION_DECL (void (* gen_jacobian), (
  27.       double *mparam,
  28.       double **dyda,
  29.       int nrows,
  30.       int ncols
  31.       ));           /* Routine to compute Jacobian and goal vector */
  32.  
  33.    FUNCTION_DECL (void (* function), (
  34.       double *mparams,
  35.       double *newvalue,
  36.       int nrows,
  37.       int ncols
  38.       ));         /* Routine for computing value of the function */
  39.  
  40.    FUNCTION_DECL (void (* new_position_action), (
  41.       double *mparam,
  42.       int ncols));      /* Called when parameter values change */
  43.  
  44.    } Marquardt_info;
  45.  
  46. /*>> Explanation :
  47.  
  48.    The foregoing structure controls the marquardt algorithm.  The meaning
  49. of each parameter is as follows.
  50.  
  51. Num_Loops    Controls the number of times the program will go
  52. around the loop of iterative improvement.  The algorithm will
  53. terminate when this number of iterations have been done or it is
  54. determined that futher iterations will not lead to improvement. A
  55. value of Num_Loops = 100 - 500 will be plenty, probably excessive.
  56. Note that the algorithm normally does not go this many iterations,
  57. because it converges first.
  58.  
  59. Min_Incr    The minimum square sum of changes to the parameters
  60. that is considered significant.  If an iteration causes an increment
  61. less than this value, then the algorithm will be deemed to have
  62. converged and will terminate.
  63.  
  64. diag        The algorithm will handle either diagonal or full
  65. symmetric covariance matrices.  A value of diag = 1 means that the
  66. covariance (weight) matrix contains just diagonal entries.  In this
  67. case, the matrix "weight" must be represented as a matrix of dimensions 
  68. 1 x nrows (not as might be thought a nrows x nrows matrix with just
  69. diagonal entries).  The first row represents the diagonal entries of
  70. the covariance matrix.  
  71.  
  72.     In the case where diag = 0, the algorithm expects a full nrows
  73. x nrows matrix of covariance values between the measured values being
  74. approximated.
  75.  
  76. weight        Weight is the inverse covariance matrix of the covariances of
  77. the measured values being approximated.  In case weight is a diagonal
  78. matrix (diag = 1) the diagonal entries represent the reciprocals of
  79. the variances of the measured values, each measurement assumed to be
  80. independent.  In the case weight is a non-diagonal matrix it must be
  81. symmetric and then represents the inverse of the full covariance
  82. matrix of the measurements.
  83.  
  84.     As explained above, if weight is a diagonal matrix, then it
  85. must be stored in one row, the single row representing the actual
  86. diagonal entries.
  87.  
  88.     If weight is a null pointer, then a diagonal identity matrix
  89. is assumed.
  90.  
  91. covar        The output covariance matrix.  This gives the
  92. covariance matrix for the outputs at the computed optimum parameter
  93. setting.  Covar is a matrix of dimension ncols x ncols and must be
  94. allocated previous to calling marquardt.  If it has the value NULL,
  95. then the covariance matrix will not be computed.
  96.  
  97. params        This is an array of length ncols containing 
  98. the parameters to be varied.  This vector is the means by which the
  99. parameter values are updated.  All parameters must be double.
  100. On input, the vector contains the initial values of the parameters and
  101. on output the final values.
  102.  
  103. goal    This is an array of length nrows giving the goal values of the
  104. function.
  105.  
  106. get_jacobian    This is the address of subroutine that must be
  107. supplied for computing the Jacobian matrix
  108. and the goal vector at the present parameter setting.  
  109. It is called with the sequence 
  110.  
  111. (void) (* get_jacobian) (params, dyda, dy, nrows, ncols);
  112.    double *params;
  113.    double **dyda;
  114.    double *dy;
  115.    int nrows, ncols;
  116.  
  117. the matrix dyda is a matrix of size nfows x ncols and dy is a vector
  118. of length nrows.  Both are already allocated inside the marquardt
  119. routine.  If the get_jacobian field contains a NULL function pointer,
  120. then the marquardt routine will find its own way to compute the
  121. jacobian.
  122.  
  123. function    This is a function supplied to the routine.  The
  124. routine seeks to minimize the difference between the value of this
  125. function and a given goal vector.  The function is called with the
  126. sequence
  127.  
  128. (void ) (* function ) (inputvalues, outputvalues, nrows, ncols)
  129.    double *inputvalues;
  130.    double *outputvalues;
  131.    int nrows, ncols;
  132.  
  133. The vector inputvalues is an array of length ncols and outputvalues is
  134. an array of length nrows.  The function must return the output
  135. values.
  136.  
  137. new_position_action  is a routine called whenever the values of the
  138. parameters are updated.  This routine may do various things, for
  139. instance change the values of the parameters to yet a different value
  140. if the value determined by the marquardt iteration is not acceptable.
  141. The routine is called as follows
  142.  
  143. new_position_action (params, ncols)
  144.   double *params;
  145.   int ncols;
  146.  
  147. <<*/
  148.  
  149. #include "marqu.s"
  150. #endif
  151.