pysolvegn.Term#

class Term(residual_func=None, jacobian_func=None, second_term_func=None, hessian_func=None, weight=None, loss=None, finite_difference=None)[source]#

A class representing a term in the least squares problem, which can be either a residual term or a regularization term.

For the following definition, the \(i\)-th term in the least squares problem is denoted as \(\mathbf{R}_i(\mathbf{p})\)

\[\min_{\mathbf{p}} \frac{1}{2} \sum_{i} w_i \sum_j \rho_i\left(\| \mathbf{r}_{i,j}(\mathbf{p}) \|^2\right)\]

Each term can be defined by two callable functions:

The Residual and Jacobian functions

The residual function \(\mathbf{r}_i(\mathbf{p})\) to minimize and the Jacobian function \(\mathbf{J}_i(\mathbf{p}) = \frac{\partial \mathbf{r}_i}{\partial \mathbf{p}}\) to compute the Jacobian matrix of the residuals with respect to the parameters.

Then the solver will build the second term \(\mathbf{g}(\mathbf{p})\) and the Hessian of the least squares problem \(\mathbf{H}(\mathbf{p})\) as:

\[\mathbf{g} = w_i \tilde{\mathbf{J}}_i^T \tilde{\mathbf{r}}_i\]

\[\mathbf{H} = w_i \tilde{\mathbf{J}}_i^T \tilde{\mathbf{J}}_i\]

such that \(\mathbf{H} \Delta \mathbf{p} = -\mathbf{g}\).

See also

For more details on notations for the optimization problem and the algorithm, please refer to the mathematical section of the documentation.
The Second term and Hessian functions

The hessian function \(\mathbf{H}_i(\mathbf{p})\) to compute the Hessian of the least squares problem and the second term function \(\mathbf{g}_i(\mathbf{p})\) to compute the second term of the least squares problem.

Then the solver will use them directly without building them from the residuals and Jacobian, such that:

\[\mathbf{g} = w_i \mathbf{g}_i(\mathbf{p})\]

\[\mathbf{H} = w_i \mathbf{H}_i(\mathbf{p})\]

Such that \(\mathbf{H} \Delta \mathbf{p} = -\mathbf{g}\).

This class is used to represent each term in the least squares problem, and can be used to define the residual and Jacobian functions for each term, as well as the second term and Hessian functions for each term, which can be used to build the least squares problem.

Parameters:

residual_func (Optional[Callable] (default=None)) – The function to compute the residuals in the least squares problem. The function should take as inputs the parameters (array-like with shape (n_parameters,)) and return the residuals as a 1D numpy array with shape (n_residuals,) representing each \(\mathbf{r}_{j}(\mathbf{p})\) where \(j=0,...,n_{\text{residuals}-1}\).
jacobian_func (Optional[Callable] (default=None)) – The function to compute the Jacobian matrix of the residuals with respect to the parameters. The function should take as inputs the parameters (array-like with shape (n_parameters,)) and return the Jacobian matrix as a 2D numpy array with shape (n_residuals, n_parameters) representing each \(\mathbf{J}_{j}(\mathbf{p})\) where \(j=0,...,n_{\text{residuals}-1}\) such that \(\mathbf{J}_j(\mathbf{p}) = \frac{\partial \mathbf{r}_j}{\partial \mathbf{p}}\). If not provided, the Jacobian will be computed numerically using finite differences.
second_term_func (Optional[Callable] (default=None)) – The function to compute the second term \(\mathbf{g}_i(\mathbf{p})\) of the least squares problem. The function should take as inputs the parameters (array-like with shape (n_parameters,)) and return the second term as a 1D numpy array with shape (n_parameters,). If provided, loss must be “linear”.
hessian_func (Optional[Callable] (default=None)) – The function to compute the Hessian \(\mathbf{H}_i(\mathbf{p})\) of the least squares problem. The function should take as inputs the parameters (array-like with shape (n_parameters,)) and return the Hessian as a 2D numpy array with shape (n_parameters, n_parameters). If provided, loss must be “linear”.
weight (Real (default=1.0)) – The weight of the term in the least squares problem. The weight will be applied to both the residuals and the Jacobian matrix, as well as the second term and Hessian if provided.
loss (str (default="linear")) – The loss function to use for the term in the least squares problem. The loss function will be applied to the residuals of the term, and will affect how the second term and Hessian are computed from the residuals and Jacobian. Available loss functions are “linear”, “cauchy”, “arctan”, and “soft_l1”. Must be “linear” if the term is defined by the second term and Hessian functions.
finite_difference (str (default="central")) – The finite difference method to use for computing the numerical Jacobian if the Jacobian function is not provided. Must be one of "central", "forward", or "backward".

Notes

Each term must be defined by either the residual and Jacobian functions, or the second term and Hessian functions, but not both.
Hessian and second term must be provided together.
If Residual is given without Jacobian, the jacobian will be computed numerically using finite differences.

Version#

0.1.0: Initial version of the Term class.

__init__(residual_func=None, jacobian_func=None, second_term_func=None, hessian_func=None, weight=None, loss=None, finite_difference=None)[source]#

Parameters:

residual_func (Callable | None)
jacobian_func (Callable | None)
second_term_func (Callable | None)
hessian_func (Callable | None)
weight (Real | None)
loss (str | None)
finite_difference (str | None)

Methods

`__init__`([residual_func, jacobian_func, ...])
`from_gH`([second_term_func, hessian_func, weight])	Create a Term object from the second term and Hessian functions.
`from_rJ`([residual_func, jacobian_func, ...])	Create a Term object from the residual and Jacobian functions.

Attributes

`H_func`
`J_func`
`finite_difference`	[Get/Set] the finite difference method for numerical Jacobian computation of the term.
`g_func`
`hessian_func`	[Get] the Hessian function of the term.
`jacobian_func`	[Get] the Jacobian function of the term.
`loss`	[Get/Set] the loss function of the term in the least squares problem.
`r_func`
`residual_func`	[Get] the residual function of the term.
`rho_function`	[Get] the rho function corresponding to the current loss function of the term.
`second_term_func`	[Get] the second term function of the term.
`type`	[Get] the type of the term, which can be either "rJ" for terms defined by residual and Jacobian functions, or "gH" for terms defined by second term and Hessian functions.
`use_finite_difference`	[Get] whether the term is using a finite difference Jacobian function.
`weight`	[Get/Set] the weight of the term in the least squares problem.