changeset 33323:0d2a6a831574 stable

doc: note fminX parameter passing removal, document alternatives (bug #55742) * NEWS.9.md: Add note describing plan for Octave 10 removal of undocumented fminsearch behavior allowing parameter passing through to fcn. Note anonymous function parameter handling example has been added to Minimizers manual section. Note that application notes were added to fminbnd, fminsearch, and fminunch docstrings. * fminsearch.m: Add application note describing discouraged use and pending removal of directly passing parameted through undocumented fminsearch feature, and preference to use anonymous functions for that purpose. * fminbnd.m, fminunc.m: Add application note describing parameter passing through the use of anonymous functions. * nonlin.txi: Add to Minimizers section an example of using an anonymous function for parameter handling with minimizaion functions.
author Nicholas R. Jankowski <jankowski.nicholas@gmail.com>
date Thu, 04 Apr 2024 15:13:32 -0400
parents 0d1f479b7824
children d512e7414e78 87a54302d126
files doc/interpreter/nonlin.txi etc/NEWS.9.md scripts/optimization/fminbnd.m scripts/optimization/fminsearch.m scripts/optimization/fminunc.m
diffstat 5 files changed, 85 insertions(+), 5 deletions(-) [+]
line wrap: on
line diff
--- a/doc/interpreter/nonlin.txi	Wed Apr 03 20:07:44 2024 +0200
+++ b/doc/interpreter/nonlin.txi	Thu Apr 04 15:13:32 2024 -0400
@@ -177,7 +177,7 @@
 function is required.  For functions which can be differentiated,
 @code{fminunc} is appropriate.  For functions with discontinuities, or for
 which a gradient search would fail, use @code{fminsearch}.
-@xref{Optimization}, for minimization with the presence of constraint
+@xref{Optimization} for minimization with the presence of constraint
 functions.  Note that searches can be made for maxima by simply inverting the
 objective function
 @tex
@@ -193,6 +193,37 @@
 
 @DOCSTRING(fminsearch)
 
+Certain minimization operations require additional parameters be passed to
+the function, @code{F}, being minimized. E.g., @w{@code{F = F(x, C)}}.
+Octave's minimizer functions are designed to only pass one optimization
+variable to @code{F}, but parameter passing can be accomplished by defining
+an @ref{Anonymous Function} that contains the necessargy parameter(s).  See
+the example below:
+
+@group
+@example
+A = 2; B = 3;
+f = @(x) sin (A*x + B);
+fminbnd (f, 0, 2)
+@result 0.8562
+@end example
+@end group
+
+Note that anonymous functions retain the value of parameters at the time they
+are defined.  Changing a parameter value after function definition will not
+affect output of the function until it is redefined:
+
+@group
+@example
+B = 4;
+fminbnd (f, 0, 2)
+@result 0.8562
+f = @(x) sin (A*x + B);
+fminbnd (f, 0, 2)
+@result 0.3562
+@end example
+@end group
+
 The function @code{humps} is a useful function for testing zero and
 extrema finding functions.
 
--- a/etc/NEWS.9.md	Wed Apr 03 20:07:44 2024 +0200
+++ b/etc/NEWS.9.md	Thu Apr 04 15:13:32 2024 -0400
@@ -29,8 +29,27 @@
 - Describe shape of outputs for `hist` (bug #65471).
 - Simplify programming notes for `patch` objects (bug #65421).
 - `vecnorm.m`: Add missing parenthesis to equation in docstring.
+- Add example to Minimizers section on using anonymous functions to pass
+  examples to functions called by minimizer functions (`fminsearch`,
+  `fminbnd`, `fminunc`).
+- Add application notes in `fminsearch`, `fminbnd`, `fminunc` indicated the
+  preferred way to pass parameters is through anonymous functions.
 - Update remaining copyright statements to 2024.
 
+### Deprecated functions, properties, and operators
+
+- `fminsearch` parameter passing:  A legacy, undocumented, and only partially
+  supported syntax for passing parameters to the minimized function `fcn`
+  called by `fminsearch` by appending them to the input argument list has
+  functioned intermittently since Octave 4.4.0.  Due to conflicts with other
+  compatibility-required input methods the documentation of this syntax was
+  removed in Octave 5.1.0, and the remaining functionality will be completely
+  removed in Octave 10.  The preferred, cross-platform compatible method of
+  passing parameters to any of the minimization functions (including
+  `fminsearch`, `fminbnd`, and `fminunc`) is through the use of Anonymous
+  Functions.  Specific examples of this can be found in the @ref{Minimizers}
+  section of the GNU Octave manual.
+
 
 Summary of important user-visible changes for version 9 (2024-03-12):
 ---------------------------------------------------------------------
--- a/scripts/optimization/fminbnd.m	Wed Apr 03 20:07:44 2024 +0200
+++ b/scripts/optimization/fminbnd.m	Thu Apr 04 15:13:32 2024 -0400
@@ -73,11 +73,20 @@
 ## The algorithm was terminated by a user @code{OutputFcn}.
 ## @end itemize
 ##
-## Programming Notes: The search for a minimum is restricted to be in the
+## Application Notes:
+## @enumerate
+## @item
+## The search for a minimum is restricted to be in the
 ## finite interval bound by @var{a} and @var{b}.  If you have only one initial
 ## point to begin searching from then you will need to use an unconstrained
 ## minimization algorithm such as @code{fminunc} or @code{fminsearch}.
 ## @code{fminbnd} internally uses a Golden Section search strategy.
+## @item
+## Use @ref{Anonymous Functions} to pass additional parameters to @var{fcn}.
+## For specific examples of doing so for @code{fminbnd} and other
+## minimization functions see the @ref{Minimizers} section of the GNU Octave
+## manual.
+## @end enumerate
 ## @seealso{fzero, fminunc, fminsearch, optimset}
 ## @end deftypefn
 
--- a/scripts/optimization/fminsearch.m	Wed Apr 03 20:07:44 2024 +0200
+++ b/scripts/optimization/fminsearch.m	Thu Apr 04 15:13:32 2024 -0400
@@ -115,8 +115,20 @@
 ## fminsearch (@@(x) (x(1)-5).^2+(x(2)-8).^4, [0;0])
 ## @end example
 ##
-## Note: If you need to find the minimum of a single variable function it is
+## Application Notes:
+## @enumerate
+## @item
+## If you need to find the minimum of a single variable function it is
 ## probably better to use @code{fminbnd}.
+## @item
+## The legacy, undocumented syntax for passing parameters to @var{fcn} by
+## appending them to the input argument list after @var{options} is
+## discouraged and will  be completely removed in Octave 10.  The
+## preferred, cross-platform compatible method of passing parameters to
+## @var{fcn} is through use of @ref{Anonymous Functions}.  For specific
+## examples of doing so for @code{fminsearch} and other minimization
+## functions see the @ref{Minimizers} section of the GNU Octave manual.
+## @end enumerate
 ## @seealso{fminbnd, fminunc, optimset}
 ## @end deftypefn
 
--- a/scripts/optimization/fminunc.m	Wed Apr 03 20:07:44 2024 +0200
+++ b/scripts/optimization/fminunc.m	Thu Apr 04 15:13:32 2024 -0400
@@ -109,13 +109,22 @@
 ## solution @var{x}, and approximate Hessian (@var{hess}) at the solution
 ## @var{x}.
 ##
-## Application Notes: If the objective function is a single nonlinear equation
+## Application Notes:
+## @enumerate
+## @item
+## If the objective function is a single nonlinear equation
 ## of one variable then using @code{fminbnd} is usually a better choice.
-##
+## @item
 ## The algorithm used by @code{fminunc} is a gradient search which depends
 ## on the objective function being differentiable.  If the function has
 ## discontinuities it may be better to use a derivative-free algorithm such as
 ## @code{fminsearch}.
+## @item
+## Use @ref{Anonymous Functions} to pass additional parameters to @var{fcn}.
+## For specific examples of doing so for @code{fminunc} and other
+## minimization functions see the @ref{Minimizers} section of the GNU Octave
+## manual.
+## @end enumerate
 ## @seealso{fminbnd, fminsearch, optimset}
 ## @end deftypefn