# HG changeset patch
# User Nicholas R. Jankowski <jankowski.nicholas@gmail.com>
# Date 1712260856 14400
# Node ID d512e7414e788098c694eb93a4f6934e59916269
# Parent  44c24e64567764589caeca1ff696776ba7d2a63f# Parent  0d2a6a831574fc2e5b7c196da02dba97c8680adc
maint: Merge stable to default.

diff -r 44c24e645677 -r d512e7414e78 doc/interpreter/nonlin.txi
--- a/doc/interpreter/nonlin.txi	Thu Apr 04 15:07:13 2024 -0400
+++ b/doc/interpreter/nonlin.txi	Thu Apr 04 16:00:56 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.
 
diff -r 44c24e645677 -r d512e7414e78 etc/NEWS.9.md
--- a/etc/NEWS.9.md	Thu Apr 04 15:07:13 2024 -0400
+++ b/etc/NEWS.9.md	Thu Apr 04 16:00:56 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):
 ---------------------------------------------------------------------
diff -r 44c24e645677 -r d512e7414e78 scripts/optimization/fminbnd.m
--- a/scripts/optimization/fminbnd.m	Thu Apr 04 15:07:13 2024 -0400
+++ b/scripts/optimization/fminbnd.m	Thu Apr 04 16:00:56 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
 
diff -r 44c24e645677 -r d512e7414e78 scripts/optimization/fminsearch.m
--- a/scripts/optimization/fminsearch.m	Thu Apr 04 15:07:13 2024 -0400
+++ b/scripts/optimization/fminsearch.m	Thu Apr 04 16:00:56 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
 
diff -r 44c24e645677 -r d512e7414e78 scripts/optimization/fminunc.m
--- a/scripts/optimization/fminunc.m	Thu Apr 04 15:07:13 2024 -0400
+++ b/scripts/optimization/fminunc.m	Thu Apr 04 16:00:56 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