time | calls | line |
---|
| | 1 | function options = optimset(varargin)
|
| | 2 | %OPTIMSET Create/alter optimization OPTIONS structure.
|
| | 3 | % OPTIONS = OPTIMSET('PARAM1',VALUE1,'PARAM2',VALUE2,...) creates an
|
| | 4 | % optimization options structure OPTIONS in which the named parameters have
|
| | 5 | % the specified values. Any unspecified parameters are set to [] (parameters
|
| | 6 | % with value [] indicate to use the default value for that parameter when
|
| | 7 | % OPTIONS is passed to the optimization function). It is sufficient to type
|
| | 8 | % only the leading characters that uniquely identify the parameter. Case is
|
| | 9 | % ignored for parameter names.
|
| | 10 | % NOTE: For values that are strings, the complete string is required.
|
| | 11 | %
|
| | 12 | % OPTIONS = OPTIMSET(OLDOPTS,'PARAM1',VALUE1,...) creates a copy of OLDOPTS
|
| | 13 | % with the named parameters altered with the specified values.
|
| | 14 | %
|
| | 15 | % OPTIONS = OPTIMSET(OLDOPTS,NEWOPTS) combines an existing options structure
|
| | 16 | % OLDOPTS with a new options structure NEWOPTS. Any parameters in NEWOPTS
|
| | 17 | % with non-empty values overwrite the corresponding old parameters in
|
| | 18 | % OLDOPTS.
|
| | 19 | %
|
| | 20 | % OPTIMSET with no input arguments and no output arguments displays all
|
| | 21 | % parameter names and their possible values, with defaults shown in {}
|
| | 22 | % when the default is the same for all functions that use that parameter.
|
| | 23 | % Use OPTIMSET(OPTIMFUNCTION) to see parameters for a specific function.
|
| | 24 | %
|
| | 25 | % OPTIONS = OPTIMSET (with no input arguments) creates an options structure
|
| | 26 | % OPTIONS where all the fields are set to [].
|
| | 27 | %
|
| | 28 | % OPTIONS = OPTIMSET(OPTIMFUNCTION) creates an options structure with all
|
| | 29 | % the parameter names and default values relevant to the optimization
|
| | 30 | % function named in OPTIMFUNCTION. For example,
|
| | 31 | % optimset('fminbnd')
|
| | 32 | % or
|
| | 33 | % optimset(@fminbnd)
|
| | 34 | % returns an options structure containing all the parameter names and
|
| | 35 | % default values relevant to the function 'fminbnd'.
|
| | 36 | %
|
| | 37 | %OPTIMSET PARAMETERS for MATLAB
|
| | 38 | %Display - Level of display [ off | iter | notify | final ]
|
| | 39 | %MaxFunEvals - Maximum number of function evaluations allowed
|
| | 40 | % [ positive integer ]
|
| | 41 | %MaxIter - Maximum number of iterations allowed [ positive scalar ]
|
| | 42 | %TolFun - Termination tolerance on the function value [ positive scalar ]
|
| | 43 | %TolX - Termination tolerance on X [ positive scalar ]
|
| | 44 | %FunValCheck - Check for invalid values, such as NaN or complex, from
|
| | 45 | % user-supplied functions [ {off} | on ]
|
| | 46 | %OutputFcn - Name(s) of output function [ {[]} | function ]
|
| | 47 | % All output functions are called by the solver after each
|
| | 48 | % iteration.
|
| | 49 | %PlotFcns - Name(s) of plot function [ {[]} | function ]
|
| | 50 | % Function(s) used to plot various quantities in every iteration
|
| | 51 | %
|
| | 52 | % Note to Optimization Toolbox users:
|
| | 53 | % To see the parameters for a specific function, check the documentation page
|
| | 54 | % for that function. For instance, enter
|
| | 55 | % doc fmincon
|
| | 56 | % to open the reference page for fmincon.
|
| | 57 | %
|
| | 58 | % You can also see the options in the Optimization Tool. Enter
|
| | 59 | % optimtool
|
| | 60 | %
|
| | 61 | % Examples:
|
| | 62 | % To create an options structure with the default parameters for FZERO
|
| | 63 | % options = optimset('fzero');
|
| | 64 | % To create an options structure with TolFun equal to 1e-3
|
| | 65 | % options = optimset('TolFun',1e-3);
|
| | 66 | % To change the Display value of options to 'iter'
|
| | 67 | % options = optimset(options,'Display','iter');
|
| | 68 | %
|
| | 69 | % See also OPTIMGET, FZERO, FMINBND, FMINSEARCH, LSQNONNEG.
|
| | 70 |
|
| | 71 | % Copyright 1984-2014 The MathWorks, Inc.
|
| | 72 |
|
| | 73 | % Check to see if an optimoptions object has been passed in as the first
|
| | 74 | % input argument.
|
| 26 | 75 | if nargin > 0 && isa(varargin{1}, 'optim.options.SolverOptions')
|
| | 76 | error(message('MATLAB:optimset:OptimOptionsFirstInput'));
|
| | 77 | end
|
| | 78 |
|
| | 79 | % Check to see if an optimoptions object has been passed in as the second
|
| | 80 | % input argument.
|
| 26 | 81 | if nargin > 1 && isa(varargin{2}, 'optim.options.SolverOptions')
|
| | 82 | error(message('MATLAB:optimset:OptimOptionsSecondInput'));
|
| | 83 | end
|
| | 84 |
|
| | 85 | % Check to see if Optimization Toolbox options are available
|
| 26 | 86 | [sharedoptim, fulloptim] = uselargeoptimstruct;
|
| | 87 |
|
| | 88 | % Print out possible values of properties.
|
| 26 | 89 | if (nargin == 0) && (nargout == 0)
|
| | 90 | if sharedoptim
|
| | 91 | fprintf([' Display: [ off | iter | iter-detailed | ', ...
|
| | 92 | 'notify | notify-detailed | final | final-detailed ]\n']);
|
| | 93 | else
|
| | 94 | fprintf([' Display: [ off | iter | ', ...
|
| | 95 | 'notify | final ]\n']);
|
| | 96 | end
|
| | 97 | fprintf(' MaxFunEvals: [ positive scalar ]\n');
|
| | 98 | fprintf(' MaxIter: [ positive scalar ]\n');
|
| | 99 | fprintf(' TolFun: [ positive scalar ]\n');
|
| | 100 | fprintf(' TolX: [ positive scalar ]\n');
|
| | 101 | fprintf(' FunValCheck: [ on | {off} ]\n');
|
| | 102 | fprintf(' OutputFcn: [ function | {[]} ]\n');
|
| | 103 | fprintf(' PlotFcns: [ function | {[]} ]\n');
|
| | 104 |
|
| | 105 | % Display specialized options if appropriate
|
| | 106 | if sharedoptim
|
| | 107 | displayoptimoptions;
|
| | 108 | else
|
| | 109 | fprintf('\n');
|
| | 110 | end
|
| | 111 | return;
|
| | 112 | end
|
| | 113 |
|
| | 114 | % Create a cell array of all the field names
|
| 26 | 115 | allfields = {'Display'; 'MaxFunEvals';'MaxIter';'TolFun';'TolX'; ...
|
| | 116 | 'FunValCheck';'OutputFcn';'PlotFcns'};
|
| | 117 |
|
| | 118 | % Include specialized options if appropriate
|
| 26 | 119 | if sharedoptim
|
0.01 | 26 | 120 | optimfields = optimoptiongetfields;
|
| 26 | 121 | allfields = [allfields; optimfields];
|
| 26 | 122 | end
|
| | 123 |
|
| | 124 | % Create a struct of all the fields with all values set to []
|
| | 125 | % create cell array
|
| 26 | 126 | structinput = cell(2,length(allfields));
|
| | 127 | % fields go in first row
|
| 26 | 128 | structinput(1,:) = allfields';
|
| | 129 | % []'s go in second row
|
| 26 | 130 | structinput(2,:) = {[]};
|
| | 131 | % turn it into correctly ordered comma separated list and call struct
|
0.01 | 26 | 132 | options = struct(structinput{:});
|
| | 133 |
|
| 26 | 134 | numberargs = nargin; % we might change this value, so assign it
|
| | 135 | % If we pass in a function name then return the defaults.
|
| 26 | 136 | if (numberargs==1) && (ischar(varargin{1}) || isa(varargin{1},'function_handle') )
|
| | 137 | if ischar(varargin{1})
|
| | 138 | funcname = lower(varargin{1});
|
| | 139 | if ~exist(funcname,'file')
|
| | 140 | error(message('MATLAB:optimset:FcnNotFoundOnPath', funcname));
|
| | 141 | end
|
| | 142 | elseif isa(varargin{1},'function_handle')
|
| | 143 | funcname = func2str(varargin{1});
|
| | 144 | end
|
| | 145 | try
|
| | 146 | optionsfcn = feval(varargin{1},'defaults');
|
| | 147 | catch ME
|
| | 148 | error(message('MATLAB:optimset:NoDefaultsForFcn', funcname));
|
| | 149 | end
|
| | 150 | % The defaults from the optim functions don't include all the fields
|
| | 151 | % typically, so run the rest of optimset as if called with
|
| | 152 | % optimset(options,optionsfcn)
|
| | 153 | % to get all the fields.
|
| | 154 | varargin{1} = options;
|
| | 155 | varargin{2} = optionsfcn;
|
| | 156 | numberargs = 2;
|
| | 157 | end
|
| | 158 |
|
| 26 | 159 | Names = allfields;
|
| 26 | 160 | m = size(Names,1);
|
| 26 | 161 | names = lower(Names);
|
| | 162 |
|
| 26 | 163 | i = 1;
|
| 26 | 164 | while i <= numberargs
|
| 26 | 165 | arg = varargin{i};
|
| 26 | 166 | if ischar(arg) % arg is an option name
|
| 26 | 167 | break;
|
| | 168 | end
|
| | 169 | if ~isempty(arg) % [] is a valid options argument
|
| | 170 | if ~isa(arg,'struct')
|
| | 171 | error(message('MATLAB:optimset:NoParamNameOrStruct', i));
|
| | 172 | end
|
| | 173 | for j = 1:m
|
| | 174 | if any(strcmp(fieldnames(arg),Names{j,:}))
|
| | 175 | val = arg.(Names{j,:});
|
| | 176 | else
|
| | 177 | val = [];
|
| | 178 | end
|
| | 179 | if ~isempty(val)
|
| | 180 | if ischar(val)
|
| | 181 | val = lower(deblank(val));
|
| | 182 | end
|
| | 183 | options.(Names{j,:}) = checkfield(Names{j,:},val,sharedoptim);
|
| | 184 | end
|
| | 185 | end
|
| | 186 | end
|
| | 187 | i = i + 1;
|
| | 188 | end
|
| | 189 |
|
| | 190 | % A finite state machine to parse name-value pairs.
|
| 26 | 191 | if rem(numberargs-i+1,2) ~= 0
|
| | 192 | error(message('MATLAB:optimset:ArgNameValueMismatch'));
|
| | 193 | end
|
| 26 | 194 | expectval = 0; % start expecting a name, not a value
|
| 26 | 195 | while i <= numberargs
|
| 156 | 196 | arg = varargin{i};
|
| | 197 |
|
| 156 | 198 | if ~expectval
|
| 78 | 199 | if ~ischar(arg)
|
| | 200 | error(message('MATLAB:optimset:ParamNotString', i));
|
| | 201 | end
|
| | 202 |
|
| 78 | 203 | lowArg = lower(arg);
|
0.05 | 78 | 204 | j = strmatch(lowArg,names);
|
| 78 | 205 | if isempty(j) % if no matches
|
| | 206 | % Check for recently deprecated options. These will be ignored
|
| | 207 | % in a later release, but for now we will throw a specific
|
| | 208 | % error.
|
| | 209 | deprecatedOptionCheck(lowArg);
|
| | 210 | if fulloptim
|
| | 211 | % Slightly different error message if optim tbs ix
|
| | 212 | % available.
|
| | 213 | suggestOptimoptions(arg);
|
| | 214 | end
|
| | 215 |
|
| | 216 | % Error out - compose internationalization-friendly message with hyperlinks
|
| | 217 | linkStr = getString(message('MATLAB:optimset:LinkToReferencePage'));
|
| | 218 | stringWithLink = formatStringWithHyperlinks(linkStr,'doc optimset');
|
| | 219 | error(message('MATLAB:optimset:InvalidParamNameWithLink', ...
|
| | 220 | arg, stringWithLink));
|
| | 221 |
|
| | 222 |
|
| 78 | 223 | elseif length(j) > 1 % if more than one match
|
| | 224 | % Check for any exact matches (in case any names are subsets of others)
|
| | 225 | k = strmatch(lowArg,names,'exact');
|
| | 226 | if length(k) == 1
|
| | 227 | j = k;
|
| | 228 | else
|
| | 229 | allnames = ['(' Names{j(1),:}];
|
| | 230 | for k = j(2:length(j))'
|
| | 231 | allnames = [allnames ', ' Names{k,:}];
|
| | 232 | end
|
| | 233 | allnames = [allnames,')'];
|
| | 234 | error(message('MATLAB:optimset:AmbiguousParamName', arg, allnames));
|
| | 235 | end
|
| | 236 | end
|
| | 237 |
|
| | 238 | % Check for options that are on a deprecation path.
|
| 78 | 239 | onDeprecationPathOptionCheck(lowArg, sharedoptim);
|
| | 240 |
|
| | 241 | % We expect a value next
|
| 78 | 242 | expectval = 1;
|
| 78 | 243 | else
|
| 78 | 244 | if ischar(arg)
|
| 52 | 245 | arg = lower(deblank(arg));
|
| 52 | 246 | end
|
0.01 | 78 | 247 | options.(Names{j,:}) = checkfield(Names{j,:},arg,sharedoptim);
|
| 78 | 248 | expectval = 0;
|
| 78 | 249 | end
|
| 156 | 250 | i = i + 1;
|
| 156 | 251 | end
|
| | 252 |
|
| 26 | 253 | if expectval
|
| | 254 | error(message('MATLAB:optimset:NoValueForParam', arg));
|
| | 255 | end
|
Other subfunctions in this file are not included in this listing.