template<class fitterT>
class mx::math::fit::levmarInterface< fitterT >

A templatized interface to the levmar package.

Requires a fitter class, which conforms to one of the following minimum specifications. To use the finite difference jacobian calculation:

//This will cause the levmar_dif routine to be used
template<typename _realT>
struct dif_fitter
{
   typedef _realT realT; //required
 
   static void func( realT *p,   // [in]  the parameter values, size m
                     realT *hx,  // [out] the error for this p, size n
                     int m,      // [in]  the number of parameters
                     int n,      // [in]  the number of data points
                     void *adata // [in]  auxiliary data
                   )
    {
       //do stuff here . . .
    }
};

If you wish to provide your own jacobian:

//This will cause the levmar_der routine to be used
template<typename _realT>
struct der_fitter
{
   typedef _realT realT; //required
 
   typdef bool hasJacobian; //this signals that jacf exists and should be used.
 
   static void func( realT *p,   // [in]  the parameter values, size m
                     realT *hx,  // [out] the error for this p, size n
                     int m,      // [in]  the number of parameters
                     int n,      // [in]  the number of data points
                     void *adata // [in]  auxiliary data
                   )
   {
       //do stuff here . . .
   }
 
   // This is the jacobian.
   static void jacf( realT *p,   // [in]  the parameter values, size m
                     realT *j,   // [out] the jacobian for this p, size n
                     int m,      // [in]  the number of parameters
                     int n,      // [in]  the number of data points
                     void *adata // [in]  auxiliary data
                   )
   {
       //do stuff here . . .
   }
 
};

Note that if your fitter has a jacobian function (jacf), you must define

typedef bool hasJacobian;

for it to be used.

Template Parameters

fitterT a class with at least the minimum interface described above.

Definition at line 115 of file levmarInterface.hpp.

#include <math/fit/levmarInterface.hpp>

Inheritance diagram for mx::math::fit::levmarInterface< fitterT >:

Public Member Functions
	levmarInterface ()
	Default constructor.
	levmarInterface (realT i_p, realT i_x, int i_m, int i_n, void *i_adata)
	Setup constructor.
	~levmarInterface ()
	Destructor.
void	nParams (int i_m)
	Set number of parameters, but don't allocate.
int	nParams ()
	Get the current number of parameters.
void	allocate_params ()
	Allocate parameters array based on previous call to nParams.
void	allocate_params (int i_m)
	Set number of parameters and allocate.
void	point_params (realT *i_p)
	Point the parameter pointer at an externally allocated array.
void	point_params (realT *i_p, int i_m)
	Point the parameter pointer at an externally allocated array.
void	set_params (realT *i_p)
	Copy parameters to the parameter array.
realT *	get_params ()
	Get current pointer array address.
void	set_itmax (int i_itmax)
	Set the maximum number of iterations.
int	get_itmax ()
	Get the maximum number of iterations.
void	allocate_work ()
	Allocate the work and covar matrices.
void	set_opts (int n, realT val)
	Set one of the minimization options to val.
void	set_opts_default (int n=-1)
	Set one or all of the minimization options to the default.
realT	get_opts (int n)
	Get the current value of an option.
int	fit ()
	Perform the fit.
realT	get_initial_norm ()
	Returns the L2-norm before minimization occurs.
realT	get_final_norm ()
	Returns the L2-norm at the end of the minimization.
int	get_iterations ()
	Get the number of iterations taken during the minimization.
int	get_reason_code ()
	Get a code specifying the reason minimization terminated.
std::string	get_reason_string ()
	Get the descriptive string describing the reason minimization terminated.
int	get_fevals ()
	Get the number of function evaluations during the minimization.
int	get_jevals ()
	Get the number of jacobian evaluations during the minimization.
int	get_nlinsys ()
	Get the number of linear system solutions during the minimization.
double	get_deltaT ()
	Get the elapsed time of the fit.
template<typename iosT, char comment = '#'>
iosT &	dumpParameters (iosT &ios)
	Output current parameters to a stream.
template<char comment = '#'>
std::ostream &	dumpParameters ()
	Dump the parameter vector to stdout.
template<typename iosT, char comment = '#'>
iosT &	dumpReport (iosT &ios, bool dumpParams=true)
	Output current parameters to a stream.
template<char comment = '#'>
std::ostream &	dumpReport (bool dumpParams=true)
	Dump a status report to stdout.

Public Attributes
realT *	x
	I: measurement vector. NULL implies a zero vector.
int	n
	I: measurement vector dimension.
realT	opts [LM_OPTS_SZ]
	Options passed to the minimization routines. See set_opts for details.
realT	info [LM_INFO_SZ]
	Information regarding the minimization.
double	deltaT
	Elapsed time of the fitting procedure.
realT *	work
	Working memory passed to the levmar routines.
int	work_sz
	The current size of the work array.
realT *	covar
	Covariance matrix corresponding to LS solution; mxm.
int	covar_sz
	The current size of the covar array.
bool	getCovar
	Controls whether the covar array is allocated.
void *	adata
	Pointer to possibly additional data, passed uninterpreted to func & jacf.

Protected Attributes
realT *	p
	Parameter array. On input is the initial estimates. On output has the estimated solution.
realT *	init_p
	Parameter array on input, saved for comparison.
int	m
	Parameter vector dimension (i.e. number of unknowns).
bool	own_p
	Flag indicating whether the p array is owned by this object (for de-allocation).
int	itmax
	Maximum number of iterations, default is 100.

Constructor & Destructor Documentation

◆ levmarInterface() [1/2]

template<class fitterT>

mx::math::fit::levmarInterface< fitterT >::levmarInterface ( )

Default constructor.

With this constructor, you must set the parameter, data, and adata before calling fit().

Definition at line 378 of file levmarInterface.hpp.

◆ levmarInterface() [2/2]

template<class fitterT>

mx::math::fit::levmarInterface< fitterT >::levmarInterface	(	typename fitterT::realT *	i_p,
		typename fitterT::realT *	i_x,
		int	i_m,
		int	i_n,
		void *	i_adata )

Setup constructor.

with this constructor fit() will work immediately.

Parameters

[in]	i_p	pointer to the initial parameter guess
[in]	i_x	pointer to the data (can be NULL)
[in]	i_m	the size of i_p
[in]	i_n	the size of i_x
[in]	i_adata	pointer to auxiliary data (can be NULL)

Definition at line 384 of file levmarInterface.hpp.

References adata, m, n, p, and x.

◆ ~levmarInterface()

template<class fitterT>

mx::math::fit::levmarInterface< fitterT >::~levmarInterface ( )

Destructor.

Frees the work and covar matrices.

Definition at line 397 of file levmarInterface.hpp.

References covar, init_p, own_p, p, and work.

Member Function Documentation

◆ allocate_params() [1/2]

template<class fitterT>

void mx::math::fit::levmarInterface< fitterT >::allocate_params ( )

Allocate parameters array based on previous call to nParams.

Definition at line 440 of file levmarInterface.hpp.

References m, own_p, and p.

Referenced by allocate_params(), mx::math::fit::fitEmpirical2DGen< mx::math::fit::empirical2D_fitter< realT > >::setFixed(), mx::math::fit::fitGaussian2D< mx::math::fit::gaussian2D_sym_fitter< realT > >::setFixed(), mx::math::fit::fitGaussian2D< mx::math::fit::gaussian2D_sym_fitter< realT > >::setFixed(), and mx::math::fit::fitMoffat2D< mx::math::fit::moffat2D_sym_fitter< realT > >::setFixed().

◆ allocate_params() [2/2]

template<class fitterT>

void mx::math::fit::levmarInterface< fitterT >::allocate_params ( int i_m )

Set number of parameters and allocate.

Definition at line 453 of file levmarInterface.hpp.

References allocate_params(), and nParams().

◆ allocate_work()

template<class fitterT>

void mx::math::fit::levmarInterface< fitterT >::allocate_work ( )

Allocate the work and covar matrices.

Uses a function object specialized for whether or not there is a jacobian to determine the size of work.

Definition at line 528 of file levmarInterface.hpp.

References covar, covar_sz, getCovar, m, n, work, and work_sz.

Referenced by fit().

◆ dumpParameters() [1/2]

template<class fitterT>

template<char comment>

std::ostream & mx::math::fit::levmarInterface< fitterT >::dumpParameters ( )

Dump the parameter vector to stdout.

Template Parameters

comment is a comment character to start each line. Can be '\0'.

Definition at line 758 of file levmarInterface.hpp.

References dumpParameters().

◆ dumpParameters() [2/2]

template<class fitterT>

template<typename iosT, char comment>

iosT & mx::math::fit::levmarInterface< fitterT >::dumpParameters ( iosT & ios )

Output current parameters to a stream.

Prints a formatted list of all current fit parameters.

Template Parameters

iosT	is a std::ostream-like type.
comment	is a comment character to start each line. Can be '\0'.

Parameters

[in] ios a std::ostream-like stream.

Definition at line 741 of file levmarInterface.hpp.

References init_p, m, and p.

Referenced by dumpParameters(), and dumpReport().

◆ dumpReport() [1/2]

template<class fitterT>

template<char comment>

std::ostream & mx::math::fit::levmarInterface< fitterT >::dumpReport ( bool dumpParams = true )

Dump a status report to stdout.

Template Parameters

comment is a comment character to start each line. Can be '\0'.

Parameters

[in] dumpParams [optional] whether or not to dump the parameters.

Definition at line 787 of file levmarInterface.hpp.

References dumpReport().

◆ dumpReport() [2/2]

template<class fitterT>

template<typename iosT, char comment>

iosT & mx::math::fit::levmarInterface< fitterT >::dumpReport	(	iosT &	ios,
		bool	dumpParams = true )

Output current parameters to a stream.

Prints a formatted list of all current fit parameters.

Template Parameters

iosT	is a std::ostream-like type.
comment	is a comment character to start each line. Can be '\0'.

Parameters

[in]	ios	a std::ostream-like stream.
[in]	dumpParams	[optional] whether or not to dump the parameters.

Definition at line 765 of file levmarInterface.hpp.

References mx::dumpGitStatus(), dumpParameters(), get_deltaT(), get_fevals(), get_final_norm(), get_initial_norm(), get_iterations(), get_jevals(), and get_reason_string().

Referenced by dumpReport().

◆ fit()

template<class fitterT>

int mx::math::fit::levmarInterface< fitterT >::fit ( )

Perform the fit.

This calls allocate_work, and then dispatches the levmar routine appropriate for fitterT.

Definition at line 629 of file levmarInterface.hpp.

References adata, allocate_work(), covar, deltaT, mx::sys::get_curr_time(), info, init_p, itmax, m, n, opts, p, work, and x.

Referenced by mx::math::fit::fitGaussian1D< _realT >::fit(), and mx::math::fit::fitGaussian2D< mx::math::fit::gaussian2D_sym_fitter< realT > >::fit().

◆ get_deltaT()

template<class fitterT>

double mx::math::fit::levmarInterface< fitterT >::get_deltaT ( )

inline

Get the elapsed time of the fit.

Definition at line 308 of file levmarInterface.hpp.

References deltaT.

Referenced by dumpReport().

◆ get_fevals()

template<class fitterT>

int mx::math::fit::levmarInterface< fitterT >::get_fevals ( )

Get the number of function evaluations during the minimization.

Definition at line 691 of file levmarInterface.hpp.

References info.

Referenced by dumpReport().

◆ get_final_norm()

template<class fitterT>

fitterT::realT mx::math::fit::levmarInterface< fitterT >::get_final_norm ( )

Returns the L2-norm at the end of the minimization.

Definition at line 673 of file levmarInterface.hpp.

References info.

Referenced by dumpReport().

◆ get_initial_norm()

template<class fitterT>

fitterT::realT mx::math::fit::levmarInterface< fitterT >::get_initial_norm ( )

Returns the L2-norm before minimization occurs.

Definition at line 667 of file levmarInterface.hpp.

References info.

Referenced by dumpReport().

◆ get_iterations()

template<class fitterT>

int mx::math::fit::levmarInterface< fitterT >::get_iterations ( )

Get the number of iterations taken during the minimization.

Definition at line 679 of file levmarInterface.hpp.

References info.

Referenced by dumpReport().

◆ get_itmax()

template<class fitterT>

int mx::math::fit::levmarInterface< fitterT >::get_itmax ( )

Get the maximum number of iterations.

Definition at line 485 of file levmarInterface.hpp.

References itmax.

◆ get_jevals()

template<class fitterT>

int mx::math::fit::levmarInterface< fitterT >::get_jevals ( )

Get the number of jacobian evaluations during the minimization.

Definition at line 697 of file levmarInterface.hpp.

References info.

Referenced by dumpReport().

◆ get_nlinsys()

template<class fitterT>

int mx::math::fit::levmarInterface< fitterT >::get_nlinsys ( )

Get the number of linear system solutions during the minimization.

Definition at line 703 of file levmarInterface.hpp.

References info.

◆ get_opts()

template<class fitterT>

fitterT::realT mx::math::fit::levmarInterface< fitterT >::get_opts ( int n )

Get the current value of an option.

See set_opts for a description of the options

Parameters

n	the option number

Definition at line 597 of file levmarInterface.hpp.

References n, and opts.

◆ get_params()

template<class fitterT>

fitterT::realT * mx::math::fit::levmarInterface< fitterT >::get_params ( )

Get current pointer array address.

Definition at line 491 of file levmarInterface.hpp.

References p.

◆ get_reason_code()

template<class fitterT>

int mx::math::fit::levmarInterface< fitterT >::get_reason_code ( )

Get a code specifying the reason minimization terminated.

Definition at line 685 of file levmarInterface.hpp.

References info.

Referenced by get_reason_string().

◆ get_reason_string()

template<class fitterT>

std::string mx::math::fit::levmarInterface< fitterT >::get_reason_string ( )

Get the descriptive string describing the reason minimization terminated.

Definition at line 709 of file levmarInterface.hpp.

References get_reason_code().

Referenced by dumpReport().

◆ nParams() [1/2]

template<class fitterT>

int mx::math::fit::levmarInterface< fitterT >::nParams ( )

Get the current number of parameters.

Returns: the current number of parameters (m)

Definition at line 434 of file levmarInterface.hpp.

References m.

◆ nParams() [2/2]

template<class fitterT>

void mx::math::fit::levmarInterface< fitterT >::nParams ( int i_m )

Set number of parameters, but don't allocate.

Parameters

[in] i_m the number of parameters

Definition at line 413 of file levmarInterface.hpp.

References init_p, m, own_p, and p.

Referenced by allocate_params(), and point_params().

◆ point_params() [1/2]

template<class fitterT>

void mx::math::fit::levmarInterface< fitterT >::point_params ( realT * i_p )

Point the parameter pointer at an externally allocated array.

Definition at line 461 of file levmarInterface.hpp.

References own_p, and p.

Referenced by point_params().

◆ point_params() [2/2]

template<class fitterT>

void mx::math::fit::levmarInterface< fitterT >::point_params	(	realT *	i_p,
		int	i_m )

Point the parameter pointer at an externally allocated array.

Definition at line 472 of file levmarInterface.hpp.

References nParams(), and point_params().

◆ set_itmax()

template<class fitterT>

void mx::math::fit::levmarInterface< fitterT >::set_itmax ( int i_itmax )

Set the maximum number of iterations.

Sets itmax. Initialization default is itmax = 100

Parameters

i_itmax the new value of itmax to set

Definition at line 479 of file levmarInterface.hpp.

References itmax.

◆ set_opts()

template<class fitterT>

void mx::math::fit::levmarInterface< fitterT >::set_opts	(	int	n,
		realT	val )

Set one of the minimization options to val.

The options correspond to:

0: the scale factor of the initial \( \mu \), default is 1e-3.

1: \( \epsilon_1 \) Stopping threshold for ||J^T e||_inf, default is 1e-17.

2: \( \epsilon_2 \) Stopping threshold for ||Dp||_2, default is 1e-17.

3: \( \epsilon_3 \) Stopping threshold for ||e||_2, default is 1e-17.

4: \( \Delta_{diff}\) Stepsize for finite differences, default is 1e-6.

Parameters

n	is the option number
val	is the value to set

Definition at line 564 of file levmarInterface.hpp.

References n, and opts.

◆ set_opts_default()

template<class fitterT>

void mx::math::fit::levmarInterface< fitterT >::set_opts_default ( int n = -1 )

Set one or all of the minimization options to the default.

See set_opts for discription of the options.

Parameters

n	the option number. Pass -1 to set all options to defaults.

Definition at line 570 of file levmarInterface.hpp.

References n, and opts.

◆ set_params()

template<class fitterT>

void mx::math::fit::levmarInterface< fitterT >::set_params ( realT * i_p )

Copy parameters to the parameter array.

This assumes that either the array was allocated (i.e. with allocate_params) or that point_params has been called

Definition at line 497 of file levmarInterface.hpp.

References m, and p.

Member Data Documentation

◆ adata

template<class fitterT>

void* mx::math::fit::levmarInterface< fitterT >::adata

Pointer to possibly additional data, passed uninterpreted to func & jacf.

Set to NULL if not needed.

Definition at line 173 of file levmarInterface.hpp.

Referenced by levmarInterface(), and fit().

◆ covar

template<class fitterT>

realT* mx::math::fit::levmarInterface< fitterT >::covar

Covariance matrix corresponding to LS solution; mxm.

Here this is allocated to size m-x-m by allocate_work, but if you don't want it allocated and calculated set getCovar to false and NULL will be passed.

Definition at line 162 of file levmarInterface.hpp.

Referenced by ~levmarInterface(), allocate_work(), and fit().