irtr

 IRTR   Implicit Riemannian Trust-Region (with tCG inner solve)

 This performs a retraction-based, trust-region minimization of an objective 
 function on a Riemannian manifold.

 x = irtr(fns,params) returns the minimizer (a point on the manifold)
 [x,stats] = irtr(fns,params) also returns some statistics from the algorithm

 The struct fns contains the function handles necessary to perform the 
 optimization:
  fns.R(x,eta) : retract tangent vector eta at T_x M to the manifold
  fns.g(x,eta,zeta) : Riemannian metric at T_x M 
  fns.proj(x,eta) : Project eta from nearby T_x M to T_x M (used in iteration to 
                    combat round-off)
  fns.f(x) : Compute the objective function at x
  fns.fgrad(x) : Compute the gradient of f at x, returning a tangent vector
  fns.fhess(x,eta) : Apply the Hessian of f, hess_x: T_x M -> T_x M
  fns.rho(x,eta) : Compute the rho-ratio: rho(x,eta)
 Optionally, three other methods may be specified:
  fns.rhosearch(x,eta,zeta,rhoprime) : Returns a value tau such that 
                                         rho(x,eta+tau*zeta) >= rhoprime
  fns.prec(x,eta) : apply an s.p.d. preconditioner for the inner iteration, 
                    to eta, a tangent vector in T_x M
  fns.dist(x,y) : returns the distance on the manifold between points x and y
  fns.randT(x) : returns a very small random tangent vector in T_x M
 More info:
  fns.dist is used to measure the distance from solution and is only referenced 
      if params.xsol was specified.
  fns.randT is used to initialize the trust-region subproblem with a random vector,
      to encourage escape from an exact critical point.
  fns.prec is a preconditioner for the model minimization, a positive-definite 
      (undr fns.g) mapping from T_x M to T_x M

 Parameters to the solver include:
 Required parameters:
   params.x0        - An initial iterate. Because IRTR does not know what the 
                      manifold is, this is mandatory.
   params.xsol      - For testing distance from solution using fns.dist
   params.verbosity - Level of verbosity: 
                      0 is silent, 1 has one-line info, 2 has detailed info
   params.debug     - Debugging tests: 
                      0 is silent, 1 has some, 2 has a lot, 
                      3 is more than anyone wants to know
   params.max_outer - Maximum number of outer iterations (default: 100)
   params.min_inner - Minimum number of inner iterations (default: 0). 
                      Only in effect if using randomized initial tangent vectors.
   params.max_inner - Maximum number of inner iterations (default: inf). 
                      Recommended: dimension of manifold.
   params.epsilon   - Outer Convergence tolerance (absolute)
   params.kappa     - Inner kappa convergence tolerance
   params.theta     - Inner theta convergence tolerance
   params.rho_prime - Accept/reject ratio
   params.testgh    - perform some simple numerical testing of gradient and Hessian

 The stats output is a struct array, with fields:
  k  - the outer iteration number for the stats
  ng - the norm of the gradient, sqrt(g(x,gradfx,gradfx))
  fx - the current value under the objective function
  rho - the performance ratio for the iterate
  time - the wallclock time for the outer iteration
  numinner - the number of inner iterations used to compute the next iterate
  dist     - the distance from the solution

 See also rtr