Mercurial > hg > octave-lyh
annotate scripts/optimization/optimset.m @ 14387:966ec84e7858
doc: Update optimset docstring with details of FunValCheck option.
* optimset.m: Update optimset docstring with details of FunValCheck option.
author | Rik <octave@nomad.inbox5.com> |
---|---|
date | Sat, 18 Feb 2012 12:54:41 -0800 |
parents | b76f0740940e |
children | f8bb15f6a19b |
rev | line source |
---|---|
14138
72c96de7a403
maint: update copyright notices for 2012
John W. Eaton <jwe@octave.org>
parents:
13836
diff
changeset
|
1 ## Copyright (C) 2007-2012 John W. Eaton |
8647
06f5dd901f30
implement registering of optimization options
Jaroslav Hajek <highegg@gmail.com>
parents:
8598
diff
changeset
|
2 ## Copyright (C) 2009 VZLU Prague |
6226 | 3 ## |
4 ## This file is part of Octave. | |
5 ## | |
6 ## Octave is free software; you can redistribute it and/or modify it | |
7 ## under the terms of the GNU General Public License as published by | |
7016 | 8 ## the Free Software Foundation; either version 3 of the License, or (at |
9 ## your option) any later version. | |
6226 | 10 ## |
11 ## Octave is distributed in the hope that it will be useful, but | |
12 ## WITHOUT ANY WARRANTY; without even the implied warranty of | |
13 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
14 ## General Public License for more details. | |
15 ## | |
16 ## You should have received a copy of the GNU General Public License | |
7016 | 17 ## along with Octave; see the file COPYING. If not, see |
18 ## <http://www.gnu.org/licenses/>. | |
6226 | 19 |
20 ## -*- texinfo -*- | |
10793
be55736a0783
Grammarcheck the documentation from m-files.
Rik <octave@nomad.inbox5.com>
parents:
10635
diff
changeset
|
21 ## @deftypefn {Function File} {} optimset () |
6226 | 22 ## @deftypefnx {Function File} {} optimset (@var{par}, @var{val}, @dots{}) |
23 ## @deftypefnx {Function File} {} optimset (@var{old}, @var{par}, @var{val}, @dots{}) | |
24 ## @deftypefnx {Function File} {} optimset (@var{old}, @var{new}) | |
25 ## Create options struct for optimization functions. | |
13797
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
26 ## |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
27 ## Valid parameters are: |
14366
b76f0740940e
doc: Periodic grammar check of documentation.
Rik <octave@nomad.inbox5.com>
parents:
14363
diff
changeset
|
28 ## |
13797
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
29 ## @itemize @bullet |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
30 ## @item AutoScaling |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
31 ## |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
32 ## @item ComplexEqn |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
33 ## |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
34 ## @item FinDiffType |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
35 ## |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
36 ## @item FunValCheck |
14387
966ec84e7858
doc: Update optimset docstring with details of FunValCheck option.
Rik <octave@nomad.inbox5.com>
parents:
14366
diff
changeset
|
37 ## When enabled, display an error if the objective function returns an invalid |
966ec84e7858
doc: Update optimset docstring with details of FunValCheck option.
Rik <octave@nomad.inbox5.com>
parents:
14366
diff
changeset
|
38 ## value (a complex value, NaN, or Inf). Must be set to "on" or "off" |
966ec84e7858
doc: Update optimset docstring with details of FunValCheck option.
Rik <octave@nomad.inbox5.com>
parents:
14366
diff
changeset
|
39 ## [default]. Note: the functions @code{fzero} and @code{fminbnd} correctly |
966ec84e7858
doc: Update optimset docstring with details of FunValCheck option.
Rik <octave@nomad.inbox5.com>
parents:
14366
diff
changeset
|
40 ## handle Inf values and only complex values or NaN will cause an error in this |
966ec84e7858
doc: Update optimset docstring with details of FunValCheck option.
Rik <octave@nomad.inbox5.com>
parents:
14366
diff
changeset
|
41 ## case. |
13797
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
42 ## |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
43 ## @item GradObj |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
44 ## When set to "on", the function to be minimized must return a second argument |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
45 ## which is the gradient, or first derivative, of the function at the point |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
46 ## @var{x}. If set to "off" [default], the gradient is computed via finite |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
47 ## differences. |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
48 ## |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
49 ## @item Jacobian |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
50 ## When set to "on", the function to be minimized must return a second argument |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
51 ## which is the Jacobian, or first derivative, of the function at the point |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
52 ## @var{x}. If set to "off" [default], the Jacobian is computed via finite |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
53 ## differences. |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
54 ## |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
55 ## @item MaxFunEvals |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
56 ## Maximum number of function evaluations before optimization stops. |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
57 ## Must be a positive integer. |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
58 ## |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
59 ## @item MaxIter |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
60 ## Maximum number of algorithm iterations before optimization stops. |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
61 ## Must be a positive integer. |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
62 ## |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
63 ## @item OutputFcn |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
64 ## A user-defined function executed once per algorithm iteration. |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
65 ## |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
66 ## @item TolFun |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
67 ## Termination criterion for the function output. If the difference in the |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
68 ## calculated objective function between one algorithm iteration and the next |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
69 ## is less than @code{TolFun} the optimization stops. Must be a positive |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
70 ## scalar. |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
71 ## |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
72 ## @item TolX |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
73 ## Termination criterion for the function input. If the difference in @var{x}, |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
74 ## the current search point, between one algorithm iteration and the next is |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
75 ## less than @code{TolX} the optimization stops. Must be a positive scalar. |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
76 ## |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
77 ## @item TypicalX |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
78 ## |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
79 ## @item Updating |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
80 ## @end itemize |
6226 | 81 ## @end deftypefn |
82 | |
83 function retval = optimset (varargin) | |
84 | |
85 nargs = nargin (); | |
86 | |
87 ## Add more as needed. | |
8647
06f5dd901f30
implement registering of optimization options
Jaroslav Hajek <highegg@gmail.com>
parents:
8598
diff
changeset
|
88 opts = __all_opts__ (); |
6226 | 89 |
90 if (nargs == 0) | |
91 if (nargout == 0) | |
92 ## Display possibilities. | |
8647
06f5dd901f30
implement registering of optimization options
Jaroslav Hajek <highegg@gmail.com>
parents:
8598
diff
changeset
|
93 puts ("\nAll possible optimization options:\n\n"); |
06f5dd901f30
implement registering of optimization options
Jaroslav Hajek <highegg@gmail.com>
parents:
8598
diff
changeset
|
94 printf (" %s\n", opts{:}); |
06f5dd901f30
implement registering of optimization options
Jaroslav Hajek <highegg@gmail.com>
parents:
8598
diff
changeset
|
95 puts ("\n"); |
6226 | 96 else |
13183
cc1fd6a58151
optimset.m: When called with 1 output argument, return a struct with all possible options initialized to [].
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
97 ## Return struct with all options initialized to [] |
cc1fd6a58151
optimset.m: When called with 1 output argument, return a struct with all possible options initialized to [].
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
98 retval = cell2struct (repmat ({[]}, size (opts)), opts, 2); |
6226 | 99 endif |
100 elseif (nargs == 1 && ischar (varargin{1})) | |
101 ## Return defaults for named function. | |
102 fcn = varargin{1}; | |
8596
8833c0b18eb2
enable default settings queries in optim funcs
Jaroslav Hajek <highegg@gmail.com>
parents:
8304
diff
changeset
|
103 try |
11407
ed827ffa5a43
optimset, optimget, __all_opts__: consistently use lower case for storing and searching options
John W. Eaton <jwe@octave.org>
parents:
11346
diff
changeset
|
104 retval = feval (fcn, "defaults"); |
8596
8833c0b18eb2
enable default settings queries in optim funcs
Jaroslav Hajek <highegg@gmail.com>
parents:
8304
diff
changeset
|
105 catch |
10635
d1978e7364ad
Print name of function in error() string messages.
Rik <octave@nomad.inbox5.com>
parents:
8920
diff
changeset
|
106 error ("optimset: no defaults for function `%s'", fcn); |
8598 | 107 end_try_catch |
6226 | 108 elseif (nargs == 2 && isstruct (varargin{1}) && isstruct (varargin{2})) |
109 ## Set slots in old from nonempties in new. Should we be checking | |
110 ## to ensure that the field names are expected? | |
111 old = varargin{1}; | |
112 new = varargin{2}; | |
6227 | 113 fnames = fieldnames (old); |
8647
06f5dd901f30
implement registering of optimization options
Jaroslav Hajek <highegg@gmail.com>
parents:
8598
diff
changeset
|
114 ## skip validation if we're in the internal query |
06f5dd901f30
implement registering of optimization options
Jaroslav Hajek <highegg@gmail.com>
parents:
8598
diff
changeset
|
115 validation = ! isempty (opts); |
11407
ed827ffa5a43
optimset, optimget, __all_opts__: consistently use lower case for storing and searching options
John W. Eaton <jwe@octave.org>
parents:
11346
diff
changeset
|
116 lopts = tolower (opts); |
6226 | 117 for [val, key] = new |
8647
06f5dd901f30
implement registering of optimization options
Jaroslav Hajek <highegg@gmail.com>
parents:
8598
diff
changeset
|
118 if (validation) |
06f5dd901f30
implement registering of optimization options
Jaroslav Hajek <highegg@gmail.com>
parents:
8598
diff
changeset
|
119 ## Case insensitive lookup in all options. |
11451
48cb431db87b
optimset: remove "i" option from call to lookup
John W. Eaton <jwe@octave.org>
parents:
11407
diff
changeset
|
120 i = lookup (lopts, tolower (key)); |
8647
06f5dd901f30
implement registering of optimization options
Jaroslav Hajek <highegg@gmail.com>
parents:
8598
diff
changeset
|
121 ## Validate option. |
06f5dd901f30
implement registering of optimization options
Jaroslav Hajek <highegg@gmail.com>
parents:
8598
diff
changeset
|
122 if (i > 0 && strcmpi (opts{i}, key)) |
06f5dd901f30
implement registering of optimization options
Jaroslav Hajek <highegg@gmail.com>
parents:
8598
diff
changeset
|
123 ## Use correct case. |
06f5dd901f30
implement registering of optimization options
Jaroslav Hajek <highegg@gmail.com>
parents:
8598
diff
changeset
|
124 key = opts{i}; |
06f5dd901f30
implement registering of optimization options
Jaroslav Hajek <highegg@gmail.com>
parents:
8598
diff
changeset
|
125 else |
06f5dd901f30
implement registering of optimization options
Jaroslav Hajek <highegg@gmail.com>
parents:
8598
diff
changeset
|
126 warning ("unrecognized option: %s", key); |
06f5dd901f30
implement registering of optimization options
Jaroslav Hajek <highegg@gmail.com>
parents:
8598
diff
changeset
|
127 endif |
6226 | 128 endif |
6227 | 129 old.(key) = val; |
6226 | 130 endfor |
131 retval = old; | |
132 elseif (rem (nargs, 2) && isstruct (varargin{1})) | |
133 ## Set values in old from name/value pairs. | |
11121
134d357e1c03
optimization/optimset.m: Use cell2struct instead of struct to handle cell arrays as options
Olaf Till <olaf.till@uni-jena.de>
parents:
10793
diff
changeset
|
134 pairs = reshape (varargin(2:end), 2, []); |
134d357e1c03
optimization/optimset.m: Use cell2struct instead of struct to handle cell arrays as options
Olaf Till <olaf.till@uni-jena.de>
parents:
10793
diff
changeset
|
135 retval = optimset (varargin{1}, cell2struct (pairs(2, :), pairs(1, :), 2)); |
6226 | 136 elseif (rem (nargs, 2) == 0) |
137 ## Create struct. Default values are replaced by those specified by | |
138 ## name/value pairs. | |
11121
134d357e1c03
optimization/optimset.m: Use cell2struct instead of struct to handle cell arrays as options
Olaf Till <olaf.till@uni-jena.de>
parents:
10793
diff
changeset
|
139 pairs = reshape (varargin, 2, []); |
134d357e1c03
optimization/optimset.m: Use cell2struct instead of struct to handle cell arrays as options
Olaf Till <olaf.till@uni-jena.de>
parents:
10793
diff
changeset
|
140 retval = optimset (struct (), cell2struct (pairs(2, :), pairs(1, :), 2)); |
6226 | 141 else |
142 print_usage (); | |
143 endif | |
144 | |
145 endfunction | |
8647
06f5dd901f30
implement registering of optimization options
Jaroslav Hajek <highegg@gmail.com>
parents:
8598
diff
changeset
|
146 |
13183
cc1fd6a58151
optimset.m: When called with 1 output argument, return a struct with all possible options initialized to [].
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
147 |
14363
f3d52523cde1
Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents:
14138
diff
changeset
|
148 %!assert (optimget (optimset ("tolx", 1e-2), "tOLx"), 1e-2) |
f3d52523cde1
Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents:
14138
diff
changeset
|
149 %!assert (isfield (optimset ("tolFun", 1e-3), "TolFun")) |
13183
cc1fd6a58151
optimset.m: When called with 1 output argument, return a struct with all possible options initialized to [].
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
150 |
cc1fd6a58151
optimset.m: When called with 1 output argument, return a struct with all possible options initialized to [].
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
151 %!error (optimset ("%NOT_A_REAL_FUNCTION_NAME%")) |
cc1fd6a58151
optimset.m: When called with 1 output argument, return a struct with all possible options initialized to [].
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
152 |