API Reference#

This section contains a detailed description of the functions included in pysolvegn. The reference describes how the methods work and which parameters can be used. It assumes that you have an understanding of the key concepts. The API is organized into several sections, each corresponding to a specific aspect of the package.

For more detailed explanations of the mathematical background, please refer to the Mathematical Background section of the documentation.

See also

Solver Function#

The main function of the package is the solve_gauss_newton function, which implements the Gauss-Newton optimization algorithm for solving non-linear least squares problems. This function takes as input Callable objects allowing to compute the values of a function and its jacobian with respect to its parameters.

solve_gauss_newton(residual_func, ...[, ...])

Solve the least squares problem using the Gauss-Newton method with robust cost functions.

The package includes several robust cost functions that can be used to reduce the influence of outliers in the optimization process.

Robust Function \(\rho\)

Equation

linear

\(\rho(x) = x\)

soft_l1

\(\rho(x) = 2 * ((1 + x) ** 0.5 - 1)\)

cauchy

\(\rho(x) = \log(1 + x)\)

arctan

\(\rho(x) = \arctan(x)\)

Additional Utilities#

The package also includes additional utility functions that can be used for various purposes, such as studying the jacobian, computing the jacobian of the residuals by finite differences or creating residuals and jacobians for regularization terms.

build_numerical_jacobian(residual_func[, ...])

Build a Jacobian function for the Gauss-Newton optimization by computing the numerical derivatives of the residual function with respect to the parameters using finite differences.

build_squared_regularization(means, stds)

Build a simple squared regularization of the parameters according to a Gaussian prior on the parameters, where the residuals and jacobian of the regularization are defined as:

build_soft_squared_regularization(means, ...)

Build the residual and jacobian functions of a soft squared regularization of the parameters according to a Gaussian prior on the parameters with a soft threshold, where the regularization is null for parameters that are within a certain threshold of the mean value, and increases as the squared distance of the parameters to a bounds value relative to a standard deviation, which can be interpreted as a Gaussian prior on the parameters with a soft threshold.

study_jacobian(residual_func, jacobian_func, ...)

Study the Jacobian matrix of the least squares problem to analyze the observability of the parameters and the convergence properties of the optimization (called by verbosity level 3 of the Gauss-Newton solver).