deerlab.snlls¶

snlls(y, Amodel, par0=None, lb=None, ub=None, lbl=None, ubl=None, nnlsSolver='cvx', reg='auto', weights=None, verbose=0, regparam='aic', regparamrange=None, multistart=1, regop=None, alphareopt=0.001, extrapenalty=None, subsets=None, ftol=1e-08, xtol=1e-08, max_nfev=100000000.0, lin_tol=1e-15, lin_maxiter=10000.0, noiselvl=None, lin_frozen=None, mask=None, nonlin_frozen=None, uq=True, modeluq=False)[source]¶

Separable non-linear least squares (SNLLS) solver

Fits a linear set of parameters $\theta_\mathrm{lin}$ and non-linear parameters $\theta_\mathrm{nonlin}$ by solving the following general penalized separable non-linear least-squares problem:

$& \quad\quad \min_{\theta_\mathrm{nonlin}} \left\{ \Vert y - A(\theta_\mathrm{nonlin})\theta_\mathrm{lin}(\theta_\mathrm{nonlin}) \Vert^2 + \mathcal{P}(\theta_\mathrm{nonlin},\theta_\mathrm{lin}) \right\} \\ & \text{with} \\ & \quad\quad \theta_\mathrm{lin}(\theta_\mathrm{nonlin}) = {\arg\!\min}_{\theta} \left\{ \Vert y - A(\theta_\mathrm{nonlin})\theta \Vert^2 + \mathcal{R}(\theta) \right\} \\ & \text{subject to} \\ & \quad\quad \theta_\mathrm{lb} \leq \theta_\mathrm{nonlin} \leq \theta_\mathrm{ub} \quad\quad \theta_\mathrm{lbl} \leq \theta_\mathrm{lin} \leq \theta_\mathrm{ubl}$

If the non-linear function $A(\theta_\mathrm{nonlin})$ yields an ill-conditioned problem, the solver will include a regularization penalty $\mathcal{R}(\theta)$ (Tikhonov by default) with automated selection of the regularization parameter. Additional penalty terms $\mathcal{P}(\theta_\mathrm{nonlin},\theta_\mathrm{lin})$ can be included if specified.

Parameters:

yarray_like or list of array_like

Input dataset(s) to be fitted.

Amodelcallable

Function taking an array of non-linear parameters and returning a matrix array or a list thereof.

par0array_like

Start values of the non-linear parameters.

lbarray_like, optional

Lower bounds for the non-linear parameters, assumed unconstrained if not specified.

ubarray_like, optional

Upper bounds for the non-linear parameters, assumed unconstrained if not specified.

lblarray_like, optional

Lower bounds for the linear parameters, assumed unconstrained if not specified.

ublarray_like, optional

Upper bounds for the linear parameters, assumed unconstrained if not specified.

regboolean or string, optional

Determines the use of regularization on the solution of the linear problem.

'auto' - Automatic decision based con the condition number of the non-linear model Amodel.
True - Forces regularization regardless of the condition number
False - Disables regularization regardless of the condition number

The default is 'auto'.

regparamstring or float scalar, optional

Method for the automatic selection of the optimal regularization parameter:

'lr' - L-curve minimum-radius method (LR)
'lc' - L-curve maximum-curvature method (LC)
'cv' - Cross validation (CV)
'gcv' - Generalized Cross Validation (GCV)
'rgcv' - Robust Generalized Cross Validation (rGCV)
'srgcv' - Strong Robust Generalized Cross Validation (srGCV)
'aic' - Akaike information criterion (AIC)
'bic' - Bayesian information criterion (BIC)
'aicc' - Corrected Akaike information criterion (AICC)
'rm' - Residual method (RM)
'ee' - Extrapolated Error (EE)
'ncp' - Normalized Cumulative Periodogram (NCP)
'gml' - Generalized Maximum Likelihood (GML)
'mcl' - Mallows’ C_L (MCL)

The regularization parameter can be manually specified by passing a scalar value instead of a string. The default 'aic'.

regparamrangearray_like, optional

Search range for the optimization of the regularization parameter. Must be specified as a list [regparam_lb,regparam_ub] with the lower/upper boundaries of the regularization parameter.

regop2D array_like, optional

Regularization operator matrix, the default is the second-order differential operator.

extrapenalty: callable or list thereof, optional

Custom penalty function(s) to impose upon the solution. A single penalty must be specified as a callable function. Multiple penalties can be specified as a list of callable functons. Each function must take two inputs, a vector of non-linear parameters and a vector of linear parameters, and return a vector to be added to the residual vector (pen = fcn(pnonlin,plin)). The square of the penalty is computed internally.

alphareoptfloat scalar, optional

Relative parameter change threshold for reoptimizing the regularization parameter when using a selection method, the default is 1e-3.

nnlsSolverstring, optional

Solver used to solve a non-negative least-squares problem (if applicable):

'qp' - Optimization of the NNLS problem using the quadprog package. Only Python <= 3.10.
'cvx' - Optimization of the NNLS problem using the cvxopt package.
'fnnls' - Optimization using the fast NNLS algorithm.

The default is 'cvx'.

noiselvlarray_like, optional

Noise standard deviation of the input signal(s), if not specified it is estimated automatically.

maskarrau_like or list thereof, optional

Array (or list of arrays) containing boolean (True/False) values defining a mask over one or multiple datasets. All dataset point with enabled mask values (True) will be acoounted for during the fitting procedure. All disabled values (False) will not be inlcuded. This does not affect model evaluation and uncertainty propagation.

weightsarray_like, optional

Array of weighting coefficients for the individual signals in global fitting. If not specified all datasets are weighted inversely proportional to their noise levels.

multistartint scalar, optional

Number of starting points for global optimization, the default is 1.

xtolfloat scalar, optional

Tolerance for termination by the change of the independent variables. Default is 1e-8. The optimization process is stopped when norm(dx) < xtol * (xtol + norm(x)). If set to None, the termination by this condition is disabled.

ftolfloat scalar, optional

Tolerance for termination by the change of the cost function. Default is 1e-8. The optimization process is stopped when dF < ftol*F, and there was an adequate agreement between a local quadratic model and the true model in the last step. If set to None, the termination by this condition is disabled.

max_nfevfloat scalar, optional

Maximum number of function evaluations before the termination. the default is 1e8.

lin_maxiterfloat scalar, optional

Linear solver maximal number of iterations, the default is 1e4.

lin_tolfloat scalar, optional

Linear solver tolerance to decide when a value is defined as a zero, the default is 1e-15.

nonlin_frozenarray_like

Values for non-linear parameters to be frozen during the optimization. If set to None a non-linear parameter will be optimized, if set to a numerical value it will be fixed to it and ignored during the optimization.

lin_frozenarray_like

Values for linear parameters to be frozen during the optimization. If set to None a linear parameter will be optimized, if set to a numerical value it will be fixed to it and ignored during the optimization.

uqboolean, optional

Enable/disable the uncertainty quantification analysis. Enabled by default.

modeluqboolean, optional

Enable/disable the propagation of the parameter uncertainties to the model’s response (can be computationally costly). Disabled by default

subsetsarray_like, optional

Vector of dataset subset indices, if the datasets are passed concatenated instead of a list.

verbosescalar integer, optional

Level of verbosity during the analysis:

0 : Work silently (default).

1 : Display progress including the non-linear least-squares’ solver termination report.

2 : Display progress including the non-linear least-squares’ solver iteration details.

Caution

The verbose output from the non-linear least-squares solver uses a different definition of the cost function than DeerLab. DeerLab uses the sum of squares of the residuals divided by the number of data points, whereas the non-linear least-squares solver uses the sum of squares of the residuals divided by 2.

Returns:

deerlab.FitResult with the following fields defined:

nonlinndarray

Fitted non-linear parameters.

linndarray

Fitted linear parameters.

paramndarray

Fitted full parameter set.

modelndarray

Fitted model.

nonlinUncertdeerlab.UQResult

Uncertainty quantification of the non-linear parameter set.

linUncertdeerlab.UQResult

Uncertainty quantification of the linear parameter set.

paramUncertdeerlab.UQResult

Uncertainty quantification of the full parameter set.

modelUncertdeerlab.UQResult

Uncertainty quantification of the fitted model. Only computed if modeluq=True.

regparamscalar

Regularization parameter value used for the regularization of the linear parameters.

statsdict

Goodness of fit statistical estimators

stats['chi2red'] - Reduced chi^2 test
stats['r2'] - R^2 test
stats['rmsd'] - Root-mean squared deviation (RMSD)
stats['aic'] - Akaike information criterion
stats['aicc'] - Corrected Akaike information criterion
stats['bic'] - Bayesian information criterion
stats['autocorr'] - Autocorrelation based on Durbin–Watson statistic

successbool

Whether or not the optimizer exited successfully.

costfloat

Value of the cost function at the solution.

residualsndarray

Vector of residuals at the solution.

noiselvlndarray

Estimated or user-given noise standard deviations.