rtr

 RTR   Riemannian Trust-Region (with tCG inner solve)

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

 x = rtr(fns,params) returns the minimizer (a point on the manifold)
 [x,stats] = rtr(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)
                    Also used in debugging to check tangentiality
                    Can be set to the identity if this is not a concern.
  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
 Optionally, three other methods may be specified:
  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 RTR does not know what the 
                      manifold is, this is mandatory.
   params.Delta_bar - Maximum trust-region radius. Because RTR does not know 
                      anything about the manifold, this is mandatory.
   params.Delta0    - Initial trust-region radius. Because RTR does not know 
                      anything about the manifold, 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.min_outer - Minimum number of outer iterations (default: 0); 
                      Used only with randomization
   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
   params.useRand   - initial the trust-region solve with a random tangent vector

 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
  accepted - whether the proposed iterate was accepted or not
  numinner - the number of inner iterations used to compute the next iterate
  Delta - the trust-region radius at the outer iteration
  dist     - the distance from the solution
  cauchy   - whether the cauchy point was used in place of an updated computed 
             from a random initial tangent vector

 See also irtr