Difference between revisions of "Fminnewton.m"

From Spinach Documentation Wiki
Jump to: navigation, search
m (title format for fminnewton)
 
(basic functionallty of the current fminnewton build)
Line 1: Line 1:
 
{{DISPLAYTITLE:fminnewton.m}}
 
{{DISPLAYTITLE:fminnewton.m}}
  
Finds a local minimum of a function of several variables, based on [http://www.mathworks.com/matlabcentral/fileexchange/23245-fminlbfgs--fast-limited-memory-optimizer fminlbfgs.m] code from D. Kroon, University of Twente (Nov 2010). This version is modified to be taylored to the GRAPE (Gradient Ascent Pulse Engineering) module. Syntax:
+
Finds a local minimum (or maximum) of a function of several variables, based on [http://www.mathworks.com/matlabcentral/fileexchange/23245-fminlbfgs--fast-limited-memory-optimizer fminlbfgs.m] code from D. Kroon, University of Twente (Nov 2010).
 
 
    [x,fval,grad,hess,diag_data] = fminnewton(spin_system,cost_function,x_init,optim)
 
  
 
where the <tt>spin_system</tt> is that created from Spinach, the <tt>cost_function</tt> is a function handle to that which produces as cost, gradient, and\or Hessian as a function of an initial guess, <tt>x_init</tt>. <tt>optim</tt> is an optional argument containing the optimisation options as a pair-wise cell structure.
 
where the <tt>spin_system</tt> is that created from Spinach, the <tt>cost_function</tt> is a function handle to that which produces as cost, gradient, and\or Hessian as a function of an initial guess, <tt>x_init</tt>. <tt>optim</tt> is an optional argument containing the optimisation options as a pair-wise cell structure.
  
=Inputs=
+
==Syntax==
{| class="wikitable"
 
|'spin_system'
 
|A spin system created with Spinach should always be passed to the grape optimal control module.
 
|-
 
|'cost_function'
 
|Function handle or string which is minimized:
 
 
 
                          function [f,g,h]=cost_function(x)
 
                              f , value calculation at x;
 
                              if ( nargout > 1 )
 
                                  g , gradient calculation at x;
 
                              elseif ( nargout > 2 )
 
                                  g , gradient calculation at x;
 
                                  h , hessian calculation at x;
 
                              end
 
                          end.
 
|-
 
|'x_init'
 
|Initial guess. Scalar, vector or matrix.
 
|-
 
|'optim'
 
|Structure with optimiser options. Structure is set out in the [[optim_tols.m]] function. Five optimisation methods are available: Steepest descent, BFGS, SR1, limited memory BFGS, and Newton-Raphson method. The default is l-BFGS which is fast and memory efficient.
 
 
 
Extended description of optimiser options:
 
 
 
  optim.method -  Optimisation method:
 
          'bfgs'      Broyden-Fletcher-Goldfarb-Shanno algorithm (default)
 
                      Number of unknowns > 3000, 'lbfgs' is used.
 
          'sr1'      Symmetric rank 1 Hessian update.
 
          'lbfgs'    limited memory BFGS algorithm
 
          'steepdesc' steepest decent optimization
 
          'newton'    Newton-Raphson method (needs Hessian)
 
 
 
optim.OutputFcn -  User-defined function called at each iteration,
 
                      useful in storing convergence properties.
 
 
 
optim.lbfgs_store - Iterations to approximate the Hessian in l-BFGS
 
                          20 is default. A small for non-smooth functions
 
                          large for good quadratic approximiation.
 
 
 
  optim.tolX      -  Termination tolerance on x, default 1e-6.
 
 
 
  optim.tolF      -  Termination tolerance on function, default 1e-6.
 
 
 
optim.max_iterations -  Maximum iterations allowed, default 100.
 
 
 
optim.tol_decrease_F -  Wolfe sufficient decrease condition on
 
                              gradient, default 0.01.
 
 
 
optim.tol_curvature    -  Wolfe curvature condition on gradient,
 
                              default 0.9.
 
 
 
optim.tau1      -  Bracket expansion if stepsize becomes larger,
 
                      default 3.
 
 
 
optim.tau2      -  Left bracket reduction in section phase,
 
                      default 0.1.
 
 
 
optim.tau3      -  Right bracket reduction in section phase,
 
                      default 0.5.
 
|}
 
 
 
=Outputs=
 
{| class="wikitable"
 
|'x'
 
|The minimiser of the function.
 
|-
 
|'fval'
 
|The minimum found at the corresponding minimiser.
 
|-
 
|'grad'
 
|The gradient at this location.
 
|-
 
|'hess'
 
|The Hessian at this location.
 
|-
 
|'diag_data'
 
|diagnostics data structure, containing complete information about the calculation. It has the following self‐explanatory fields:
 
 
 
diag_data.exit_message
 
 
 
diag_data.iteration
 
 
 
diag_data.funccount
 
 
 
diag_data.gradcount
 
  
diag_data.hesscount
+
    [x,fx,grad,hess,data]=fminnewton(cost_function,x_0,optim,hess_init)
  
diag_data.trajectory
+
==Description==
 +
This function looks at the edges of the spectrum and subtracts anything that it finds there from the entire spectrum. The assumption is that anything that's reached as far as the edge must be a streak artefact that should be removed. This is often the case in 2D and 3D NMR spectra.
  
diag_data.total_grad
+
==Arguments==
  
diag_data.total_hess
+
    cost_function  - Function handle, e.g. @cost_function,
 +
   
 +
    x_0            - Initial guess for the waveform.
 +
   
 +
    optim          - Structure providing the options for the numerical optimisation algorithm.
 +
                      See [[optim_tols.m]] for all options.
 +
                         
 +
    hess_init      - (optional) an initial Hessian to use for quasi-newton methods.
 +
                      If not provided, the identity is used as a default.
  
diag_data.minimiser
+
==Returns==
  
diag_data.fval
+
    x              - Output waveform at the end of the optimisation.
 +
                      Should be the waveform at a local minimum (or maximum) cost.
 +
   
 +
    fx            - Output cost at the end of the optimisation.
 +
   
 +
    grad          - Output gradient at the end of the optimisation.
 +
   
 +
    hess          - Output Hessian matrix at the end of the optimisation.
 +
                      Has meaning from 'bfgs', 'sr1', or 'newton', returns the identity otherwise.
 +
   
 +
    data          - data structure containing diagnostics of the optimisation algorithm.
  
diag_data.gradient
+
==Examples==
  
diag_data.hessian
+
==Notes==
 +
This function is coded both for minimisation (default) and maximisation. This option is defined in the <tt>optim</tt> structure from [[optim_tols.m]].
  
diag_data.timeTotal
+
==See also==
 +
[[linesearch.m]], [[optim_tols.m]], [[hessreg.m]], [[hessprep.m]]
  
diag_data.timeExtern
 
  
diag_data.timeIntern
+
''Revision 3374, authors: [[David Goodwin]]''
|}
 

Revision as of 17:33, 27 August 2016


Finds a local minimum (or maximum) of a function of several variables, based on fminlbfgs.m code from D. Kroon, University of Twente (Nov 2010).

where the spin_system is that created from Spinach, the cost_function is a function handle to that which produces as cost, gradient, and\or Hessian as a function of an initial guess, x_init. optim is an optional argument containing the optimisation options as a pair-wise cell structure.

Syntax

    [x,fx,grad,hess,data]=fminnewton(cost_function,x_0,optim,hess_init)

Description

This function looks at the edges of the spectrum and subtracts anything that it finds there from the entire spectrum. The assumption is that anything that's reached as far as the edge must be a streak artefact that should be removed. This is often the case in 2D and 3D NMR spectra.

Arguments

    cost_function  - Function handle, e.g. @cost_function, 
    
    x_0            - Initial guess for the waveform.
    
    optim          - Structure providing the options for the numerical optimisation algorithm.
                     See optim_tols.m for all options.
                          
    hess_init      - (optional) an initial Hessian to use for quasi-newton methods.
                     If not provided, the identity is used as a default.

Returns

    x              - Output waveform at the end of the optimisation.
                     Should be the waveform at a local minimum (or maximum) cost.
    
    fx             - Output cost at the end of the optimisation.
    
    grad           - Output gradient at the end of the optimisation.
    
    hess           - Output Hessian matrix at the end of the optimisation.
                     Has meaning from 'bfgs', 'sr1', or 'newton', returns the identity otherwise.
    
    data           - data structure containing diagnostics of the optimisation algorithm.

Examples

Notes

This function is coded both for minimisation (default) and maximisation. This option is defined in the optim structure from optim_tols.m.

See also

linesearch.m, optim_tols.m, hessreg.m, hessprep.m


Revision 3374, authors: David Goodwin