Nonlinear Solvers - General Info

1. Your problem class

The problem is the object defining your math system to solve, and is what you need to implement and provide to pressio4py to compute the needed operators to operate on. The problem must be an instance of a class meeting what we call the "residual-jacobian" API:

class Problem:
  def createResidual():
    # return a copy of the rank-1 residual
    return np.zeros(...)

  def createJacobian():
    # return a copy of the rank-2 jacobian
    return np.zeros(...)

  def residual(state, R):
    # given current state, compute residual, R

  def jacobian(state, J):
    # given current state, compute jacobian, J

2. Instantiating a solver

We currently support the following methods:

To instantiate a solver, you can use specific factory functions as follows:

solver = solvers.create_newton_raphson(problem, state, ...);
solver = solvers.create_gauss_newton(problem, state, ...);
solver = solvers.create_levenber_marquardt(problem, state, ...);

Note that the first and second arguments are your problem object and the state. These are needed at construction because presssio4py uses them to initialize all data structures needed. Please refer to each method's documentation for the details on the other arguments to pass.

3. Setting convergence and updating criteria

The solver class exposes the following methods:

class Solver:

  # set stopping criterion
  def setStoppingCriterion(value) # choose value is from the 'stop' enum

  # query stopping criterion
  def stoppingCriterion():
    return # the stored stopping criterion

  # set update criterion
  def setUpdatingCriterion(value) # choose value is from the 'update' enum

  # query update criterion
  def updatingCriterion():
    return # the stored update criterion

  # set max number of iterations
  def setMaxIterations(integer)
  # query max number of iterations
  def maxIterations():
    return # the current max num of iterations

  # this is used to set a single tol for all
  def setTolerance(float)

  # finer-grained methods for setting tolerances
  def setCorrectionAbsoluteTolerance(float)
  def setCorrectionRelativeTolerance(float)
  def setResidualAbsoluteTolerance(float)
  def setResidualRelativeTolerance(float)
  def setGradientAbsoluteTolerance(float)
  def setGradientRelativeTolerance(float)

  # querying tolerances
  def correctionAbsoluteTolerance(): return #...
  def correctionRelativeTolerance(): return #...
  def residualAbsoluteTolerance()  : return #...
  def residualRelativeTolerance()  : return #...
  def gradientAbsoluteTolerance()  : return #...
  def gradientRelativeTolerance()  : return #...
};

The convergence criterion and associated tolerance are used to decide why and when the solver needs to terminate. We currently support these termination criteria:

The update stage represents the how the current correction term is combined with state to update the latter. We currently support the following:

where is the correction computed at the n-th iteration of the solver.

4. Invoking the solve

This is best explained via a simple snippet:

from pressio4py import solvers

# assuming problem is already defined

state = np.array( # whatever initial condition )
solver = solvers.create_gauss_newton(problem, state, ...)
solver.solve(problem, state)