AbstractLeastSquaresMinimizer

class pmrf.optimize.AbstractLeastSquaresMinimizer

Bases: Module

Abstract interface for bounded least-squares minimisation algorithms.

A least-squares minimiser minimises half the squared norm of a residual vector rather than a scalar objective (ADR-0009). It honours bounds, so it searches box space and is given the box’s edges as bounds.

It may also be given hyperparameters: values the residual depends on but that are not least-squares variables, with a scalar objective of them. It then alternates a least-squares solve over y with the hyperparameters held and a step over the hyperparameters with y held. It knows nothing of what the hyperparameters are.

abstractmethod run(residual_fn: Callable[[PyTree, PyTree, Any], Array], y0: PyTree, args: Any, bounds: tuple[PyTree, PyTree] | None = None, max_iter: int = 1024, *, hyper_fn: Callable[[PyTree, PyTree, Any], Shaped[jaxlib._jax.Array, '']] | None = None, hyper0: PyTree = None, hyper_bounds: tuple[PyTree, PyTree] | None = None, **kwargs) → MinimizeResult

Execute the minimization algorithm.

Parameters:
  • residual_fn (callable) – The residual function residual_fn(y, hyper, args), returning a real 1-D vector. Half its squared norm is minimised over y. hyper is None when there are no hyperparameters.

  • y0 (PyTree) – The initial parameter guess.

  • args (Any) – Args to pass to residual_fn and hyper_fn.

  • bounds (tuple[PyTree, PyTree], optional) – The lower and upper edges of the box to search, shaped like y0. Edges may be infinite.

  • max_iter (int = 1024) – The maximum number of iterations of each solve.

  • hyper_fn (callable, optional) – The full scalar objective hyper_fn(hyper, y, args), minimised over the hyperparameters, or None. Required with hyper0; without it, only the objective reported is affected.

  • hyper0 (PyTree, optional) – The initial hyperparameters, or None if there are none.

  • hyper_bounds (tuple[PyTree, PyTree], optional) – The lower and upper edges of the hyperparameters’ box, shaped like hyper0.

  • **kwargs – Runtime arguments forward to the solver backend.

Returns:

An instance of pmrf.optimize.MinimizeResult, with the final hyperparameters in metrics.hyperparameters when any were given.

Return type:

results

property honours_bounds: bool

always.

Type:

Whether the minimiser keeps its values inside the bounds it is given