MPFIT_CONVERGENCE#

Name#

MPFIT_CONVERGENCE

Purpose#

Tests the resulting MPFIT solvers for convergence. This includes checking the MPFIT status, the fraction of max iterations used by each solver to reach its solution, the p-value of each solver from a simple \(\chi^2\) test, how many solvers got stuck in low probability regions, and how similar are the solver solutions to each other.

Calling Sequence#

convergence_metric = mpfit_convergence(parameters, lnprob, status, error_msg, $
                                       Niterations, Nfunc_evals, $
                                       DoF [, maxiter = ])

Inputs#

parametersint, float, or double array(Nparam, Nsolvers): The best fit parameters of the model as determined by MPFIT for each solver. The actual parameters contained in this array depend on the chosen model during configuration.
lnprobint, float, or double array(Nsolvers): Log-probability for each set of parameters.
statusint array(Nsolvers): The status code given by MPFIT.
error_msgstring array(Nsolvers): An error or warning message given by MPFIT.
Niterationsint array(Nsolvers): The number of MPFIT iterations completed.
Nfunc_evalsint array(Nsolvers): The number of lightning_mpfit_function.pro evaluations performed.
DoFint: The number of degrees of freedom in the fit.

Optional Input#

maxiterint, float, or double scalar: The maximum number of MPFIT iterations that could have been perform. (Default = 200)

Output#

convergence_metricstructure

A structure containing the convergence metrics and flags used to indicate if convergence was reached. (A flag of 1 indicates failure to converge.) The full description of the structure is as follows:

TAG	TYPE	DESCRIPTION
STATUS	int(Nsolvers)	The status code given by MPFIT
STATUS_FLAG	int(Nsolvers)	Flag indicating if the MPFIT status indicated failure of the algorithm (`<= 0`)
ERROR_MSG	string(Nsolvers)	Error or warning message given by MPFIT. Will be blank if no message
ITER_FRAC	double(Nsolvers)	Fraction of max iterations used by MPFIT to reach solution
ITER_FLAG	int(Nsolvers)	Flag indicating if the maximum number of iteration were used by MPFIT
PVALUE	double(Nsolvers)	P-value of fit as determined from a \(\chi^2\) test using `lnprob` and `DoF`
DOF	int	Degrees of freedom (same for each solver)
STUCK_FRAC	double	Fraction of solvers with `lnprob` > 2 above best fit solver
STUCK_FLAG	int	Flag indicating if the majority of solvers had `lnprob` > 2 above best fit solver
SIMILAR_FLAG	int(Nparam)	Flag indicating if any non-stuck solvers had different solutions (>1% difference)
NFUNC_EVALS	int(Nsolvers)	Number of `lightning_mpfit_function.pro` evaluations performed by MPFIT
CONVERGENCE_FLAG	int	Flag indicating if any other flag was issued for a convergence metric

Modification History#

2022/08/16: Created (Keith Doore)
2022/09/26: Added degrees of freedom to output structure (Keith Doore)
2023/01/23: Adjusted pvalue calculation if lnprob = NaN (Keith Doore)
2023/01/23: Removed similar_frac output (Keith Doore)