annotate scripts/optimization/optimget.m @ 30875:5d3faba0342e

doc: Ensure documentation lists output argument when it exists for all m-files. For new users of Octave it is best to show explicit calling forms in the documentation and to show a return argument when it exists. * bp-table.cc, shift.m, accumarray.m, accumdim.m, bincoeff.m, bitcmp.m, bitget.m, bitset.m, blkdiag.m, celldisp.m, cplxpair.m, dblquad.m, flip.m, fliplr.m, flipud.m, idivide.m, int2str.m, interpft.m, logspace.m, num2str.m, polyarea.m, postpad.m, prepad.m, randi.m, repmat.m, rng.m, rot90.m, rotdim.m, structfun.m, triplequad.m, uibuttongroup.m, uicontrol.m, uipanel.m, uipushtool.m, uitoggletool.m, uitoolbar.m, waitforbuttonpress.m, help.m, __additional_help_message__.m, hsv.m, im2double.m, im2frame.m, javachk.m, usejava.m, argnames.m, char.m, formula.m, inline.m, __vectorize__.m, findstr.m, flipdim.m, strmatch.m, vectorize.m, commutation_matrix.m, cond.m, cross.m, duplication_matrix.m, expm.m, orth.m, rank.m, rref.m, trace.m, vech.m, cast.m, compare_versions.m, delete.m, dir.m, fileattrib.m, grabcode.m, gunzip.m, inputname.m, license.m, list_primes.m, ls.m, mexext.m, movefile.m, namelengthmax.m, nargoutchk.m, nthargout.m, substruct.m, swapbytes.m, ver.m, verLessThan.m, what.m, fminunc.m, fsolve.m, fzero.m, optimget.m, __fdjac__.m, matlabroot.m, savepath.m, campos.m, camroll.m, camtarget.m, camup.m, camva.m, camzoom.m, clabel.m, diffuse.m, legend.m, orient.m, rticks.m, specular.m, thetaticks.m, xlim.m, xtickangle.m, xticklabels.m, xticks.m, ylim.m, ytickangle.m, yticklabels.m, yticks.m, zlim.m, ztickangle.m, zticklabels.m, zticks.m, ellipsoid.m, isocolors.m, isonormals.m, stairs.m, surfnorm.m, __actual_axis_position__.m, __pltopt__.m, close.m, graphics_toolkit.m, pan.m, print.m, printd.m, __ghostscript__.m, __gnuplot_print__.m, __opengl_print__.m, rotate3d.m, subplot.m, zoom.m, compan.m, conv.m, poly.m, polyaffine.m, polyder.m, polyint.m, polyout.m, polyreduce.m, polyvalm.m, roots.m, prefdir.m, prefsfile.m, profexplore.m, profexport.m, profshow.m, powerset.m, unique.m, arch_rnd.m, arma_rnd.m, autoreg_matrix.m, bartlett.m, blackman.m, detrend.m, durbinlevinson.m, fftconv.m, fftfilt.m, fftshift.m, fractdiff.m, hamming.m, hanning.m, hurst.m, ifftshift.m, rectangle_lw.m, rectangle_sw.m, triangle_lw.m, sinc.m, sinetone.m, sinewave.m, spectral_adf.m, spectral_xdf.m, spencer.m, ilu.m, __sprand__.m, sprand.m, sprandn.m, sprandsym.m, treelayout.m, beta.m, betainc.m, betaincinv.m, betaln.m, cosint.m, expint.m, factorial.m, gammainc.m, gammaincinv.m, lcm.m, nthroot.m, perms.m, reallog.m, realpow.m, realsqrt.m, sinint.m, hadamard.m, hankel.m, hilb.m, invhilb.m, magic.m, pascal.m, rosser.m, toeplitz.m, vander.m, wilkinson.m, center.m, corr.m, cov.m, discrete_cdf.m, discrete_inv.m, discrete_pdf.m, discrete_rnd.m, empirical_cdf.m, empirical_inv.m, empirical_pdf.m, empirical_rnd.m, kendall.m, kurtosis.m, mad.m, mean.m, meansq.m, median.m, mode.m, moment.m, range.m, ranks.m, run_count.m, skewness.m, spearman.m, statistics.m, std.m, base2dec.m, bin2dec.m, blanks.m, cstrcat.m, deblank.m, dec2base.m, dec2bin.m, dec2hex.m, hex2dec.m, index.m, regexptranslate.m, rindex.m, strcat.m, strjust.m, strtrim.m, strtrunc.m, substr.m, untabify.m, __have_feature__.m, __prog_output_assert__.m, __run_test_suite__.m, example.m, fail.m, asctime.m, calendar.m, ctime.m, date.m, etime.m: Add return arguments to @deftypefn macros where they were missing. Rename variables in functions (particularly generic "retval") to match documentation. Rename some return variables for (hopefully) better clarity (e.g., 'ax' to 'hax' to indicate it is a graphics handle to an axes object).
author Rik <rik@octave.org>
date Wed, 30 Mar 2022 20:40:27 -0700
parents 796f54d4ddbf
children 597f3ee61a48
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
27923
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
1 ########################################################################
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
2 ##
30564
796f54d4ddbf update Octave Project Developers copyright for the new year
John W. Eaton <jwe@octave.org>
parents: 29359
diff changeset
3 ## Copyright (C) 2008-2022 The Octave Project Developers
27918
b442ec6dda5c use centralized file for copyright info for individual contributors
John W. Eaton <jwe@octave.org>
parents: 26376
diff changeset
4 ##
27923
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
5 ## See the file COPYRIGHT.md in the top-level directory of this
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
6 ## distribution or <https://octave.org/copyright/>.
8304
eeaee297c0da modify optimset & implement optimget
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
7 ##
eeaee297c0da modify optimset & implement optimget
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
8 ## This file is part of Octave.
eeaee297c0da modify optimset & implement optimget
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
9 ##
24534
194eb4bd202b maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents: 23220
diff changeset
10 ## Octave is free software: you can redistribute it and/or modify it
8304
eeaee297c0da modify optimset & implement optimget
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
11 ## under the terms of the GNU General Public License as published by
24534
194eb4bd202b maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents: 23220
diff changeset
12 ## the Free Software Foundation, either version 3 of the License, or
22755
3a2b891d0b33 maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents: 22323
diff changeset
13 ## (at your option) any later version.
8304
eeaee297c0da modify optimset & implement optimget
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
14 ##
eeaee297c0da modify optimset & implement optimget
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
15 ## Octave is distributed in the hope that it will be useful, but
eeaee297c0da modify optimset & implement optimget
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
16 ## WITHOUT ANY WARRANTY; without even the implied warranty of
22755
3a2b891d0b33 maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents: 22323
diff changeset
17 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
3a2b891d0b33 maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents: 22323
diff changeset
18 ## GNU General Public License for more details.
8304
eeaee297c0da modify optimset & implement optimget
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
19 ##
eeaee297c0da modify optimset & implement optimget
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
20 ## You should have received a copy of the GNU General Public License
eeaee297c0da modify optimset & implement optimget
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
21 ## along with Octave; see the file COPYING. If not, see
24534
194eb4bd202b maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents: 23220
diff changeset
22 ## <https://www.gnu.org/licenses/>.
27923
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
23 ##
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
24 ########################################################################
8304
eeaee297c0da modify optimset & implement optimget
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
25
eeaee297c0da modify optimset & implement optimget
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
26 ## -*- texinfo -*-
30875
5d3faba0342e doc: Ensure documentation lists output argument when it exists for all m-files.
Rik <rik@octave.org>
parents: 30564
diff changeset
27 ## @deftypefn {} {@var{optval} =} optimget (@var{options}, @var{optname})
5d3faba0342e doc: Ensure documentation lists output argument when it exists for all m-files.
Rik <rik@octave.org>
parents: 30564
diff changeset
28 ## @deftypefnx {} {@var{optval} =} optimget (@var{options}, @var{optname}, @var{default})
5d3faba0342e doc: Ensure documentation lists output argument when it exists for all m-files.
Rik <rik@octave.org>
parents: 30564
diff changeset
29 ## Return the specific option @var{optname} from the optimization options
18602
8d4d78285c8e Overhaul optimset/optimget functions for Matlab compatibility (bug #41915).
Rik <rik@octave.org>
parents: 17744
diff changeset
30 ## structure @var{options} created by @code{optimset}.
8d4d78285c8e Overhaul optimset/optimget functions for Matlab compatibility (bug #41915).
Rik <rik@octave.org>
parents: 17744
diff changeset
31 ##
30875
5d3faba0342e doc: Ensure documentation lists output argument when it exists for all m-files.
Rik <rik@octave.org>
parents: 30564
diff changeset
32 ## If @var{optname} is not defined then return @var{default} if supplied,
18602
8d4d78285c8e Overhaul optimset/optimget functions for Matlab compatibility (bug #41915).
Rik <rik@octave.org>
parents: 17744
diff changeset
33 ## otherwise return an empty matrix.
8d4d78285c8e Overhaul optimset/optimget functions for Matlab compatibility (bug #41915).
Rik <rik@octave.org>
parents: 17744
diff changeset
34 ## @seealso{optimset}
8304
eeaee297c0da modify optimset & implement optimget
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
35 ## @end deftypefn
eeaee297c0da modify optimset & implement optimget
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
36
30875
5d3faba0342e doc: Ensure documentation lists output argument when it exists for all m-files.
Rik <rik@octave.org>
parents: 30564
diff changeset
37 function optval = optimget (options, optname, default)
8304
eeaee297c0da modify optimset & implement optimget
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
38
30875
5d3faba0342e doc: Ensure documentation lists output argument when it exists for all m-files.
Rik <rik@octave.org>
parents: 30564
diff changeset
39 if (nargin < 2 || ! isstruct (options) || ! ischar (optname))
8647
06f5dd901f30 implement registering of optimization options
Jaroslav Hajek <highegg@gmail.com>
parents: 8304
diff changeset
40 print_usage ();
06f5dd901f30 implement registering of optimization options
Jaroslav Hajek <highegg@gmail.com>
parents: 8304
diff changeset
41 endif
06f5dd901f30 implement registering of optimization options
Jaroslav Hajek <highegg@gmail.com>
parents: 8304
diff changeset
42
18602
8d4d78285c8e Overhaul optimset/optimget functions for Matlab compatibility (bug #41915).
Rik <rik@octave.org>
parents: 17744
diff changeset
43 ## Expand partial-length names into full names
8647
06f5dd901f30 implement registering of optimization options
Jaroslav Hajek <highegg@gmail.com>
parents: 8304
diff changeset
44 opts = __all_opts__ ();
30875
5d3faba0342e doc: Ensure documentation lists output argument when it exists for all m-files.
Rik <rik@octave.org>
parents: 30564
diff changeset
45 idx = strncmpi (opts, optname, length (optname));
16674
bc79ac595a05 allow abbreviations for optimset and optimget (bug #38999)
John W. Eaton <jwe@octave.org>
parents: 14138
diff changeset
46 nmatch = sum (idx);
8647
06f5dd901f30 implement registering of optimization options
Jaroslav Hajek <highegg@gmail.com>
parents: 8304
diff changeset
47
16674
bc79ac595a05 allow abbreviations for optimset and optimget (bug #38999)
John W. Eaton <jwe@octave.org>
parents: 14138
diff changeset
48 if (nmatch == 1)
30875
5d3faba0342e doc: Ensure documentation lists output argument when it exists for all m-files.
Rik <rik@octave.org>
parents: 30564
diff changeset
49 optname = opts{idx};
16674
bc79ac595a05 allow abbreviations for optimset and optimget (bug #38999)
John W. Eaton <jwe@octave.org>
parents: 14138
diff changeset
50 elseif (nmatch == 0)
30875
5d3faba0342e doc: Ensure documentation lists output argument when it exists for all m-files.
Rik <rik@octave.org>
parents: 30564
diff changeset
51 warning ("optimget: unrecognized option: %s", optname);
8647
06f5dd901f30 implement registering of optimization options
Jaroslav Hajek <highegg@gmail.com>
parents: 8304
diff changeset
52 else
18602
8d4d78285c8e Overhaul optimset/optimget functions for Matlab compatibility (bug #41915).
Rik <rik@octave.org>
parents: 17744
diff changeset
53 fmt = sprintf ("optimget: ambiguous option: %%s (%s%%s)",
16674
bc79ac595a05 allow abbreviations for optimset and optimget (bug #38999)
John W. Eaton <jwe@octave.org>
parents: 14138
diff changeset
54 repmat ("%s, ", 1, nmatch-1));
30875
5d3faba0342e doc: Ensure documentation lists output argument when it exists for all m-files.
Rik <rik@octave.org>
parents: 30564
diff changeset
55 warning (fmt, optname, opts{idx});
8647
06f5dd901f30 implement registering of optimization options
Jaroslav Hajek <highegg@gmail.com>
parents: 8304
diff changeset
56 endif
18602
8d4d78285c8e Overhaul optimset/optimget functions for Matlab compatibility (bug #41915).
Rik <rik@octave.org>
parents: 17744
diff changeset
57
30875
5d3faba0342e doc: Ensure documentation lists output argument when it exists for all m-files.
Rik <rik@octave.org>
parents: 30564
diff changeset
58 if (isfield (options, optname) && ! isempty (options.(optname)))
5d3faba0342e doc: Ensure documentation lists output argument when it exists for all m-files.
Rik <rik@octave.org>
parents: 30564
diff changeset
59 optval = options.(optname);
8304
eeaee297c0da modify optimset & implement optimget
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
60 elseif (nargin > 2)
30875
5d3faba0342e doc: Ensure documentation lists output argument when it exists for all m-files.
Rik <rik@octave.org>
parents: 30564
diff changeset
61 optval = default;
8304
eeaee297c0da modify optimset & implement optimget
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
62 else
30875
5d3faba0342e doc: Ensure documentation lists output argument when it exists for all m-files.
Rik <rik@octave.org>
parents: 30564
diff changeset
63 optval = [];
8304
eeaee297c0da modify optimset & implement optimget
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
64 endif
eeaee297c0da modify optimset & implement optimget
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
65
eeaee297c0da modify optimset & implement optimget
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
66 endfunction
eeaee297c0da modify optimset & implement optimget
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
67
17338
1c89599167a6 maint: End m-files with 1 blank line.
Rik <rik@octave.org>
parents: 16674
diff changeset
68
16674
bc79ac595a05 allow abbreviations for optimset and optimget (bug #38999)
John W. Eaton <jwe@octave.org>
parents: 14138
diff changeset
69 %!shared opts
bc79ac595a05 allow abbreviations for optimset and optimget (bug #38999)
John W. Eaton <jwe@octave.org>
parents: 14138
diff changeset
70 %! opts = optimset ("tolx", 0.1, "maxit", 100);
18602
8d4d78285c8e Overhaul optimset/optimget functions for Matlab compatibility (bug #41915).
Rik <rik@octave.org>
parents: 17744
diff changeset
71 %!assert (optimget (opts, "TolX"), 0.1)
8d4d78285c8e Overhaul optimset/optimget functions for Matlab compatibility (bug #41915).
Rik <rik@octave.org>
parents: 17744
diff changeset
72 %!assert (optimget (opts, "maxit"), 100)
8d4d78285c8e Overhaul optimset/optimget functions for Matlab compatibility (bug #41915).
Rik <rik@octave.org>
parents: 17744
diff changeset
73 %!assert (optimget (opts, "MaxITer"), 100)
8d4d78285c8e Overhaul optimset/optimget functions for Matlab compatibility (bug #41915).
Rik <rik@octave.org>
parents: 17744
diff changeset
74 %!assert (optimget (opts, "TolFun"), [])
8d4d78285c8e Overhaul optimset/optimget functions for Matlab compatibility (bug #41915).
Rik <rik@octave.org>
parents: 17744
diff changeset
75 %!assert (optimget (opts, "TolFun", 1e-3), 1e-3)
17338
1c89599167a6 maint: End m-files with 1 blank line.
Rik <rik@octave.org>
parents: 16674
diff changeset
76
19833
9fc020886ae9 maint: Clean up m-files to follow Octave coding conventions.
Rik <rik@octave.org>
parents: 19697
diff changeset
77 ## Test input validation
28886
d8318c12d903 test: remove unnecessary BIST tests in m-files checking for excessive number of inputs.
Rik <rik@octave.org>
parents: 28789
diff changeset
78 %!error <Invalid call> optimget ()
d8318c12d903 test: remove unnecessary BIST tests in m-files checking for excessive number of inputs.
Rik <rik@octave.org>
parents: 28789
diff changeset
79 %!error <Invalid call> optimget (1)
18602
8d4d78285c8e Overhaul optimset/optimget functions for Matlab compatibility (bug #41915).
Rik <rik@octave.org>
parents: 17744
diff changeset
80 %!error optimget (1, "name")
8d4d78285c8e Overhaul optimset/optimget functions for Matlab compatibility (bug #41915).
Rik <rik@octave.org>
parents: 17744
diff changeset
81 %!error optimget (struct (), 2)
8d4d78285c8e Overhaul optimset/optimget functions for Matlab compatibility (bug #41915).
Rik <rik@octave.org>
parents: 17744
diff changeset
82 %!warning <unrecognized option: foobar> (optimget (opts, "foobar"));
8d4d78285c8e Overhaul optimset/optimget functions for Matlab compatibility (bug #41915).
Rik <rik@octave.org>
parents: 17744
diff changeset
83 %!warning <ambiguous option: Max> (optimget (opts, "Max"));