learning target:
Record some information about levmar (c++ version)
Learning Content:
The official website URL is: http://users.ics.forth.gr/~lourakis/levmar/index.html
dlevmar_dif() function interface description
- Similar to dlevmar_der(), except that the Jacobian is internally approximated with the aid of finite differences. .
- Broyden's first-order update is used to compute the secant approximation of the Jacobian, effectively avoiding calling
- ffunc is used many times to compute finite difference approximations.
- If analytical Jacobian is available, use dlevmar_der() above.
- Returns the number of iterations (>=0) on success, -1 on failure
int dlevmar_dif(void (*func)(double *p, double *hx, int m, int n, void *adata),
- func: Describes the functional relationship of the measurement.
- double p, / I/O: Initial parameter estimates. output contains the estimated solution */
- double x, / I: Measurement vector. NULL means zero vector */
- int m, /* I: parameter vector dimension (i.e. #unknown) */
- int n, /* I: measurement vector dimension */
- int itmax, /* I: maximum number of iterations */
- double opts[5], /* I:opts[0-4]=minimum value. Options [\tau, \epsiln1, \epsilon2, \epsin3, \delta]. Initial \mu for ||J^T e||_inf, ||Dp||_2 and ||e||_2, scaling factor for the stopping threshold, and step size for the Jacobian step difference approximation, respectively. If δ < 0, centered differences are used to approximate the Jacobian, which is more accurate (but slower!) than the forward difference used by default. Set to NULL to use the default. /
double info[LM_INFO_SZ],
/ O: Information about minimization. Set to NULL if don't care
*info[0]=||e||2 at initial p.
*info[1-4]=[||e||_2, ||J^T e||_inf, ||Dp||_2, \mu/max[J^TJ]_ii], all of which are in Calculated under the estimated p.
*info[5]=# iteration,
*info[6]=termination reason: 1-stopped by small gradient J^T e
*2-stopped by small Dp
*3-stopped by itmax
*4-singular matrix. Restart from current p, increment \mu
*5 - no further error reduction possible. Restart with increased mu
*6 - stopped by small ||e||_2
*7 - stopped by invalid (i.e. NaN or Inf) "func" value; user error
*info[7] = # function evaluation
*info[ 8]=#Jacobian evaluation
*info[9]=The number of linear systems solved, that is, the number of attempts to reduce the error
*/ - double work, / I: Working memory, if NULL, allocated internally. if = NULL, assume to point to
memory block *at least LM_DIF_WORKSZ(m,n)* size (double) bytes long
*/ - double *covar, /*O: Corresponds to the covariance matrix of the LS solution; suppose to point to the mxm matrix.
* Set to NULL if not required.
*/ - void adata) / I: Pointer to additional data that may be needed, passed to func uninterpreted.
* Set to NULL if not required
*/
The original text of the dlevmar_dif() function is as follows
/*
- Similar to dlevmar_der() except that the Jacobian is approximated internally with the aid of finite differences.
- Broyden’s rank one updates are used to compute secant approximations to the Jacobian, effectively avoiding to call
- func several times for computing the finite difference approximations.
- If the analytic Jacobian is available, use dlevmar_der() above.
- Returns the number of iterations (>=0) if successful, -1 if failed
*/
int dlevmar_dif(
void (*func)(double *p, double *hx, int m, int n, void adata), / functional relation describing measurements.
* A p \in R^m yields a \hat{x} \in R^n
*/
double p, / I/O: initial parameter estimates. On output contains the estimated solution */
double x, / I: measurement vector. NULL implies a zero vector /
int m, / I: parameter vector dimension (i.e. #unknowns) /
int n, / I: measurement vector dimension /
int itmax, / I: maximum number of iterations /
double opts[5], / I: opts[0-4] = minim. options [\tau, \epsilon1, \epsilon2, \epsilon3, \delta]. Respectively the
* scale factor for initial \mu, stopping thresholds for ||J^T e||_inf, ||Dp||_2 and ||e||_2 and the
* step used in difference approximation to the Jacobian. If \delta<0, the Jacobian is approximated
* with central differences which are more accurate (but slower!) compared to the forward differences
* employed by default. Set to NULL for defaults to be used.
/
double info[LM_INFO_SZ],
/ O: information regarding the minimization. Set to NULL if don’t care
* info[0]= ||e||_2 at initial p.
* info[1-4]=[ ||e||_2, ||J^T e||_inf, ||Dp||_2, \mu/max[J^T J]_ii ], all computed at estimated p.
* info[5]= # iterations,
* info[6]=reason for terminating: 1 - stopped by small gradient J^T e
* 2 - stopped by small Dp
* 3 - stopped by itmax
* 4 - singular matrix. Restart from current p with increased \mu
* 5 - no further error reduction is possible. Restart with increased mu
* 6 - stopped by small ||e||_2
* 7 - stopped by invalid (i.e. NaN or Inf) “func” values; a user error
* info[7]= # function evaluations
* info[8]= # Jacobian evaluations
* info[9]= # linear systems solved, i.e. # attempts for reducing error
*/
double work, / I: working memory, allocated internally if NULL. If !=NULL, it is assumed to point to
* a memory chunk at least LM_DIF_WORKSZ(m, n)*sizeof(double) bytes long
*/
double covar, / O: Covariance matrix corresponding to LS solution; Assumed to point to a mxm matrix.
* Set to NULL if not needed.
*/
void adata) / I: pointer to possibly needed additional data, passed uninterpreted to func.
* Set to NULL if not needed
*/