Mercurial > hg > octave-nkf
annotate scripts/optimization/optimset.m @ 14366:b76f0740940e
doc: Periodic grammar check of documentation.
* accumarray.m, repmat.m, imshow.m, strread.m, edit.m, mkoctfile.m,
warning_ids.m, glpk.m, lsqnonneg.m, optimset.m, pqpnonneg.m, figure.m, print.m,
__print_parse_opts__.m, gmres.m, zscore.m, __init_fltk__.cc, cellfun.cc,
nproc.cc, regexp.cc, spparms.cc, dirfns.cc, file-io.cc, load-save.cc,
ov-null-mat.cc, ov-usr-fcn.cc, variables.cc: Periodic grammar check of
documentation.
author | Rik <octave@nomad.inbox5.com> |
---|---|
date | Wed, 15 Feb 2012 13:31:31 -0800 |
parents | f3d52523cde1 |
children | 966ec84e7858 |
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 |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
37 ## When enabled, display an error if the objective function returns a complex |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
38 ## value or NaN@. Must be set to "on" or "off" [default]. |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
39 ## |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
40 ## @item GradObj |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
41 ## 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
|
42 ## 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
|
43 ## @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
|
44 ## differences. |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
45 ## |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
46 ## @item Jacobian |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
47 ## 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
|
48 ## 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
|
49 ## @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
|
50 ## differences. |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
51 ## |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
52 ## @item MaxFunEvals |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
53 ## 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
|
54 ## Must be a positive integer. |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
55 ## |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
56 ## @item MaxIter |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
57 ## 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
|
58 ## Must be a positive integer. |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
59 ## |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
60 ## @item OutputFcn |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
61 ## 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
|
62 ## |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
63 ## @item TolFun |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
64 ## 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
|
65 ## 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
|
66 ## 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
|
67 ## scalar. |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
68 ## |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
69 ## @item TolX |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
70 ## 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
|
71 ## 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
|
72 ## 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
|
73 ## |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
74 ## @item TypicalX |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
75 ## |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
76 ## @item Updating |
5289d7c2460d
optimset.m: Document valid parameters for optimization functions.
Carnë Draug <carandraug+dev@gmail.com>
parents:
11523
diff
changeset
|
77 ## @end itemize |
6226 | 78 ## @end deftypefn |
79 | |
80 function retval = optimset (varargin) | |
81 | |
82 nargs = nargin (); | |
83 | |
84 ## Add more as needed. | |
8647
06f5dd901f30
implement registering of optimization options
Jaroslav Hajek <highegg@gmail.com>
parents:
8598
diff
changeset
|
85 opts = __all_opts__ (); |
6226 | 86 |
87 if (nargs == 0) | |
88 if (nargout == 0) | |
89 ## Display possibilities. | |
8647
06f5dd901f30
implement registering of optimization options
Jaroslav Hajek <highegg@gmail.com>
parents:
8598
diff
changeset
|
90 puts ("\nAll possible optimization options:\n\n"); |
06f5dd901f30
implement registering of optimization options
Jaroslav Hajek <highegg@gmail.com>
parents:
8598
diff
changeset
|
91 printf (" %s\n", opts{:}); |
06f5dd901f30
implement registering of optimization options
Jaroslav Hajek <highegg@gmail.com>
parents:
8598
diff
changeset
|
92 puts ("\n"); |
6226 | 93 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
|
94 ## 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
|
95 retval = cell2struct (repmat ({[]}, size (opts)), opts, 2); |
6226 | 96 endif |
97 elseif (nargs == 1 && ischar (varargin{1})) | |
98 ## Return defaults for named function. | |
99 fcn = varargin{1}; | |
8596
8833c0b18eb2
enable default settings queries in optim funcs
Jaroslav Hajek <highegg@gmail.com>
parents:
8304
diff
changeset
|
100 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
|
101 retval = feval (fcn, "defaults"); |
8596
8833c0b18eb2
enable default settings queries in optim funcs
Jaroslav Hajek <highegg@gmail.com>
parents:
8304
diff
changeset
|
102 catch |
10635
d1978e7364ad
Print name of function in error() string messages.
Rik <octave@nomad.inbox5.com>
parents:
8920
diff
changeset
|
103 error ("optimset: no defaults for function `%s'", fcn); |
8598 | 104 end_try_catch |
6226 | 105 elseif (nargs == 2 && isstruct (varargin{1}) && isstruct (varargin{2})) |
106 ## Set slots in old from nonempties in new. Should we be checking | |
107 ## to ensure that the field names are expected? | |
108 old = varargin{1}; | |
109 new = varargin{2}; | |
6227 | 110 fnames = fieldnames (old); |
8647
06f5dd901f30
implement registering of optimization options
Jaroslav Hajek <highegg@gmail.com>
parents:
8598
diff
changeset
|
111 ## skip validation if we're in the internal query |
06f5dd901f30
implement registering of optimization options
Jaroslav Hajek <highegg@gmail.com>
parents:
8598
diff
changeset
|
112 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
|
113 lopts = tolower (opts); |
6226 | 114 for [val, key] = new |
8647
06f5dd901f30
implement registering of optimization options
Jaroslav Hajek <highegg@gmail.com>
parents:
8598
diff
changeset
|
115 if (validation) |
06f5dd901f30
implement registering of optimization options
Jaroslav Hajek <highegg@gmail.com>
parents:
8598
diff
changeset
|
116 ## 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
|
117 i = lookup (lopts, tolower (key)); |
8647
06f5dd901f30
implement registering of optimization options
Jaroslav Hajek <highegg@gmail.com>
parents:
8598
diff
changeset
|
118 ## Validate option. |
06f5dd901f30
implement registering of optimization options
Jaroslav Hajek <highegg@gmail.com>
parents:
8598
diff
changeset
|
119 if (i > 0 && strcmpi (opts{i}, key)) |
06f5dd901f30
implement registering of optimization options
Jaroslav Hajek <highegg@gmail.com>
parents:
8598
diff
changeset
|
120 ## Use correct case. |
06f5dd901f30
implement registering of optimization options
Jaroslav Hajek <highegg@gmail.com>
parents:
8598
diff
changeset
|
121 key = opts{i}; |
06f5dd901f30
implement registering of optimization options
Jaroslav Hajek <highegg@gmail.com>
parents:
8598
diff
changeset
|
122 else |
06f5dd901f30
implement registering of optimization options
Jaroslav Hajek <highegg@gmail.com>
parents:
8598
diff
changeset
|
123 warning ("unrecognized option: %s", key); |
06f5dd901f30
implement registering of optimization options
Jaroslav Hajek <highegg@gmail.com>
parents:
8598
diff
changeset
|
124 endif |
6226 | 125 endif |
6227 | 126 old.(key) = val; |
6226 | 127 endfor |
128 retval = old; | |
129 elseif (rem (nargs, 2) && isstruct (varargin{1})) | |
130 ## 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
|
131 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
|
132 retval = optimset (varargin{1}, cell2struct (pairs(2, :), pairs(1, :), 2)); |
6226 | 133 elseif (rem (nargs, 2) == 0) |
134 ## Create struct. Default values are replaced by those specified by | |
135 ## 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
|
136 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
|
137 retval = optimset (struct (), cell2struct (pairs(2, :), pairs(1, :), 2)); |
6226 | 138 else |
139 print_usage (); | |
140 endif | |
141 | |
142 endfunction | |
8647
06f5dd901f30
implement registering of optimization options
Jaroslav Hajek <highegg@gmail.com>
parents:
8598
diff
changeset
|
143 |
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
|
144 |
14363
f3d52523cde1
Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents:
14138
diff
changeset
|
145 %!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
|
146 %!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
|
147 |
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
|
148 %!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
|
149 |