IterativeNonlinearLSTSQPSF.converge

giant.point_spread_functions.psf_meta:

IterativeNonlinearLSTSQPSF.converge(x, y, z)[source]

Performs iterative non-linear least squares on a PSF model until convergence has been reached for a function of the form \(z=f(x, y)\)

Iterative non-linear least squares is performed by linearizing at each step about the current best estimate of the state. This means that for each iteration, the Jacobian matrix is computed based off the current best estimate of the state, and then used to form a linear approximation of the model using a Taylor expansion. The resulting estimate is a delta from the current state, so that it is typically applied by adding the resulting update state vector to the existing states (although in some instances such as for rotations, a more complicated update application may be needed.

Iterative non-linear least squares typically needs an adequate initial guess to ensure convergence, therefore, it is recommended that the state of the class be appropriately initialized before calling this method (what is appropriate is dependent on the PSF itself.

The iteration performed in this method can be controlled using the max_iter, atol, and rtol class attributes which control the maximum number of iterations to attempt for convergence, the absolute tolerance criteria for convergence, and the relative tolerance criteria for convergence respectively.

This method use compute_jacobian() to return the Jacobian matrix for the current estimate of the state vector and update_state() to apply the estimated update at each iteration step, therefore, these methods should expect the same order of state elements.

If the iteration diverges then this method will call update_state() with None as the argument, which should typically indicate that the state parameters should be set to NaN so that other GIANT algorithms are aware the PSF fit failed.

If save_residuals is set to True, then this function will return a vector of the residuals and the covariance matrix from the fit as numpy arrays. Otherwise it returns None, None.

Parameters:

  • x (ndarray) – The x locations of the expected values as a 1D array

  • y (ndarray) – The y locations of the expected values as a 1D array

  • z (ndarray) – The expected values to fit to as a 1D array

Returns:

Either (residuals, covariance) as (n,) and (m,m) arrays if save_residuals is True or (None, None).

Return type:

Tuple[Sequence | ndarray | None, Sequence | ndarray | None]