Mercurial > octave-libgccjit

comparison scripts/optimization/fminunc.m @ 18609:923614060f1d stable

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
fminunc.m: Improve documentation. * fminunc.m: Improve documentation.
author Rik <rik@octave.org>
date Tue, 01 Apr 2014 07:06:55 -0700
parents cdcf66f4e244
children e275d15c27b5
comparison
equal deleted inserted replaced
18608:cdcf66f4e244 18609:923614060f1d
23 ## @deftypefnx {Function File} {} fminunc (@var{fcn}, @var{x0}, @var{options}) 23 ## @deftypefnx {Function File} {} fminunc (@var{fcn}, @var{x0}, @var{options})
24 ## @deftypefnx {Function File} {[@var{x}, @var{fval}, @var{info}, @var{output}, @var{grad}, @var{hess}] =} fminunc (@var{fcn}, @dots{}) 24 ## @deftypefnx {Function File} {[@var{x}, @var{fval}, @var{info}, @var{output}, @var{grad}, @var{hess}] =} fminunc (@var{fcn}, @dots{})
25 ## Solve an unconstrained optimization problem defined by the function 25 ## Solve an unconstrained optimization problem defined by the function
26 ## @var{fcn}. 26 ## @var{fcn}.
27 ## 27 ##
28 ## @var{fcn} should accepts a vector (array) defining the unknown variables, 28 ## @var{fcn} should accept a vector (array) defining the unknown variables,
29 ## and return the objective function value, optionally with gradient. 29 ## and return the objective function value, optionally with gradient.
30 ## In other words, this function attempts to determine a vector @var{x} such 30 ## @code{fminunc} attempts to determine a vector @var{x} such that
31 ## that @code{@var{fcn} (@var{x})} is a local minimum. 31 ## @code{@var{fcn} (@var{x})} is a local minimum. @var{x0} determines a
32 ## @var{x0} determines a starting guess. The shape of @var{x0} is preserved 32 ## starting guess. The shape of @var{x0} is preserved in all calls to
33 ## in all calls to @var{fcn}, but otherwise is treated as a column vector. 33 ## @var{fcn}, but otherwise is treated as a column vector.
34 ## @var{options} is a structure specifying additional options. 34 ## @var{options} is a structure specifying additional options.
35 ## Currently, @code{fminunc} recognizes these options: 35 ## Currently, @code{fminunc} recognizes these options:
36 ## @qcode{"FunValCheck"}, @qcode{"OutputFcn"}, @qcode{"TolX"}, 36 ## @qcode{"FunValCheck"}, @qcode{"OutputFcn"}, @qcode{"TolX"},
37 ## @qcode{"TolFun"}, @qcode{"MaxIter"}, @qcode{"MaxFunEvals"}, 37 ## @qcode{"TolFun"}, @qcode{"MaxIter"}, @qcode{"MaxFunEvals"},
38 ## @qcode{"GradObj"}, @qcode{"FinDiffType"}, 38 ## @qcode{"GradObj"}, @qcode{"FinDiffType"},
39 ## @qcode{"TypicalX"}, @qcode{"AutoScaling"}. 39 ## @qcode{"TypicalX"}, @qcode{"AutoScaling"}.
40 ## 40 ##
41 ## If @qcode{"GradObj"} is @qcode{"on"}, it specifies that @var{fcn}, 41 ## If @qcode{"GradObj"} is @qcode{"on"}, it specifies that @var{fcn},
42 ## called with 2 output arguments, also returns the Jacobian matrix 42 ## when called with 2 output arguments, also returns the Jacobian matrix
43 ## of right-hand sides at the requested point. @qcode{"TolX"} specifies 43 ## of partial first derivatives at the requested point.
44 ## the termination tolerance in the unknown variables, while 44 ## @code{TolX} specifies the termination tolerance for the unknown variables
45 ## @qcode{"TolFun"} is a tolerance for equations. Default is @code{1e-7} 45 ## @var{x}, while @code{TolFun} is a tolerance for the objective function
46 ## for both @qcode{"TolX"} and @qcode{"TolFun"}. 46 ## value @var{fval}. The default is @code{1e-7} for both options.
47 ## 47 ##
48 ## For description of the other options, see @code{optimset}. 48 ## For a description of the other options, see @code{optimset}.
49 ## 49 ##
50 ## On return, @var{fval} contains the value of the function @var{fcn} 50 ## On return, @var{x} is the location of the minimum and @var{fval} contains
51 ## evaluated at @var{x}, and @var{info} may be one of the following values: 51 ## the value of the objective function at @var{x}. @var{info} may be one of the
52 ## following values:
52 ## 53 ##
53 ## @table @asis 54 ## @table @asis
54 ## @item 1 55 ## @item 1
55 ## Converged to a solution point. Relative gradient error is less than 56 ## Converged to a solution point. Relative gradient error is less than
56 ## specified 57 ## specified by @code{TolFun}.
57 ## by TolFun.
58 ## 58 ##
59 ## @item 2 59 ## @item 2
60 ## Last relative step size was less that TolX. 60 ## Last relative step size was less than @code{TolX}.
61 ## 61 ##
62 ## @item 3 62 ## @item 3
63 ## Last relative decrease in function value was less than TolF. 63 ## Last relative change in function value was less than @code{TolFun}.
64 ## 64 ##
65 ## @item 0 65 ## @item 0
66 ## Iteration limit exceeded. 66 ## Iteration limit exceeded---either maximum numer of algorithm iterations
67 ## @code{MaxIter} or maximum number of function evaluations @code{MaxFunEvals}.
68 ##
69 ## @item -1
70 ## Alogrithm terminated by @code{OutputFcn}.
67 ## 71 ##
68 ## @item -3 72 ## @item -3
69 ## The trust region radius became excessively small. 73 ## The trust region radius became excessively small.
70 ## @end table 74 ## @end table
71 ## 75 ##
72 ## Optionally, fminunc can also yield a structure with convergence statistics 76 ## Optionally, @code{fminunc} can return a structure with convergence statistics
73 ## (@var{output}), the output gradient (@var{grad}) and approximate Hessian 77 ## (@var{output}), the output gradient (@var{grad}) at the solution @var{x},
74 ## (@var{hess}). 78 ## and approximate Hessian (@var{hess}) at the solution @var{x}.
75 ## 79 ##
76 ## Notes: If you only have a single nonlinear equation of one variable then 80 ## Notes: If have only a single nonlinear equation of one variable then using
77 ## using @code{fminbnd} is usually a much better idea. The algorithm used is a 81 ## @code{fminbnd} is usually a much better idea. The algorithm used is a
78 ## gradient search which depends on the objective function being differentiable. 82 ## gradient search which depends on the objective function being differentiable.
79 ## If the function has discontinuities it may be better to use a derivative-free 83 ## If the function has discontinuities it may be better to use a derivative-free
80 ## algorithm such as @code{fminsearch}. 84 ## algorithm such as @code{fminsearch}.
81 ## @seealso{fminbnd, fminsearch, optimset} 85 ## @seealso{fminbnd, fminsearch, optimset}
82 ## @end deftypefn 86 ## @end deftypefn
219 xn = norm (dg .* x); 223 xn = norm (dg .* x);
220 ## FIXME: something better? 224 ## FIXME: something better?
221 delta = factor * max (xn, 1); 225 delta = factor * max (xn, 1);
222 endif 226 endif
223 227
224 ## FIXME -- why tolf*n*xn? If abs (e) ~ abs(x) * eps is a vector 228 ## FIXME: why tolf*n*xn? If abs (e) ~ abs(x) * eps is a vector
225 ## of perturbations of x, then norm (hesr*e) <= eps*xn, i.e. by 229 ## of perturbations of x, then norm (hesr*e) <= eps*xn, i.e. by
226 ## tolf ~ eps we demand as much accuracy as we can expect. 230 ## tolf ~ eps we demand as much accuracy as we can expect.
227 if (norm (grad) <= tolf*n*xn) 231 if (norm (grad) <= tolf*n*xn)
228 info = 1; 232 info = 1;
229 break; 233 break;
285 if (ratio >= 1e-4) 289 if (ratio >= 1e-4)
286 ## Successful iteration. 290 ## Successful iteration.
287 x += s; 291 x += s;
288 xn = norm (dg .* x); 292 xn = norm (dg .* x);
289 fval = fval1; 293 fval = fval1;
290 nsuciter ++; 294 nsuciter++;
291 suc = true; 295 suc = true;
292 endif 296 endif
293 297
294 niter ++; 298 niter ++;
295 299
296 ## FIXME: should outputfcn be only called after a successful iteration? 300 ## FIXME: should outputfcn be called only after a successful iteration?
297 if (! isempty (outfcn)) 301 if (! isempty (outfcn))
298 optimvalues.iter = niter; 302 optimvalues.iter = niter;
299 optimvalues.funccount = nfev; 303 optimvalues.funccount = nfev;
300 optimvalues.fval = fval; 304 optimvalues.fval = fval;
301 optimvalues.searchdirection = s; 305 optimvalues.searchdirection = s;
342 hess = hesr'*hesr; 346 hess = hesr'*hesr;
343 endif 347 endif
344 348
345 endfunction 349 endfunction
346 350
347 ## An assistant function that evaluates a function handle and checks for 351 ## A helper function that evaluates a function and checks for bad results.
348 ## bad results.
349 function [fx, gx] = guarded_eval (fun, x) 352 function [fx, gx] = guarded_eval (fun, x)
350 if (nargout > 1) 353 if (nargout > 1)
351 [fx, gx] = fun (x); 354 [fx, gx] = fun (x);
352 else 355 else
353 fx = fun (x); 356 fx = fun (x);