# HG changeset patch
# User Nicholas R. Jankowski <jankowskin@asme.org>
# Date 1486562487 18000
#      Wed Feb 08 09:01:27 2017 -0500
# Node ID 5ae2b8c6a231c88da3d8abfce9277bfdad65a7c5
# Parent  0d4107676ddf1481560728c388beab25f4dd31e4
Implemented missing function humps.m (bug #33935)

* /scripts/optimization/humps.m: new function m-file
* /scripts/optimization/module.mk: added humps.m to
* /doc/interpreter/nonlin.txi: added doc reference to humps after nonlinear solvers and minimizers section, as the primary usage of humps is in demoing or testing zero and extrema finding functions.
* /NEWS: added humps under 'Other new functions added in 4.4

diff -r 0d4107676ddf -r 5ae2b8c6a231 NEWS
--- a/NEWS	Sun Feb 05 10:00:19 2017 -0800
+++ b/NEWS	Wed Feb 08 09:01:27 2017 -0500
@@ -21,6 +21,7 @@
  ** Other new functions added in 4.4:
 
       gsvd
+		humps
 
  ** Deprecated functions.
 
diff -r 0d4107676ddf -r 5ae2b8c6a231 doc/interpreter/nonlin.txi
--- a/doc/interpreter/nonlin.txi	Sun Feb 05 10:00:19 2017 -0800
+++ b/doc/interpreter/nonlin.txi	Wed Feb 08 09:01:27 2017 -0500
@@ -192,3 +192,7 @@
 @DOCSTRING(fminunc)
 
 @DOCSTRING(fminsearch)
+
+The funciton @code{humps} is a useful function for testing zero and extrema finding functions.  
+
+@DOCSTRING(humps)
\ No newline at end of file
diff -r 0d4107676ddf -r 5ae2b8c6a231 scripts/optimization/humps.m
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/scripts/optimization/humps.m	Wed Feb 08 09:01:27 2017 -0500
@@ -0,0 +1,106 @@
+## Copyright (C) 2017 Nicholas R. Jankowski <jankowskin@asme.org> 
+##
+## This file is part of Octave.
+##
+## Octave is free software; you can redistribute it and/or modify it
+## under the terms of the GNU General Public License as published by
+## the Free Software Foundation; either version 3 of the License, or
+## (at your option) any later version.
+## 
+## Octave is distributed in the hope that it will be useful, but
+## WITHOUT ANY WARRANTY; without even the implied warranty of
+## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+## GNU General Public License for more details.
+##
+## You should have received a copy of the GNU General Public License
+## along with Octave; see the file COPYING.  If not,
+## see <http://www.gnu.org/licenses/>.
+
+## -*- texinfo -*-
+## @deftypefn {} {} humps (@var{x})
+## @deftypefnx {} {[@var{x}, @var{y}] =} humps (@var{x})
+## Return the output of the rational function:
+##
+## @tex
+## $$y = -{ {1200x^4 - 2880x^3 + 2036x^2 - 340x - 88} \over {200x^4 - 480x^3 + 406x^2 - 138x - 17} }$$
+## @end tex
+## @ifnottex
+##
+## @example
+## @group
+##         1200*@var{x}^4 - 2880*@var{x}^3 + 2036*@var{x}^2 - 348*@var{x} - 88
+##  @var{y} = - ---------------------------------------------
+##          200*@var{x}^4 - 480*@var{x}^3 + 406*@var{x}^2 - 138*@var{x} + 17
+## @end group
+## @end example
+##
+## @end ifnottex
+##
+## @var{x} may be a scalar, vector or array.  @code{humps} is vectorized such
+## that 
+##   @var{yi} = humps(@var{xi})
+##
+## If @var{x} is omitted, the range [0:0.05:1] is used instead.
+##
+## When called with two output arguments, [@var{x},@var{y}], @var{x} will 
+## contain the input value(s), and @var{y} will contain the output from 
+## @code{humps}.
+##
+## @code{humps} has two local maxima located near @var{x} = 0.300 and 0.893, 
+## a local minimum near @var{x} = 0.637, and zeros near @var{x} = -0.132 and
+## 1.300. @code{humps} is a useful function for testing algorithms to find 
+## zeros or local minima and maxima.
+##
+## Try @code{demo humps} to see a plot of the @code{humps} function.
+##
+## @end deftypefn
+
+function varargout = humps (x = [0:0.05:1])
+  
+  if (nargin > 1)
+    print_usage ();
+  endif
+
+ y = - 4*( 300*x.^4 - 720*x.^3 + 509*x.^2 - 87*x - 22) ./ ...
+         ((10*x.^2 - 6*x + 1).*(20*x.^2 - 36*x + 17));
+
+    
+  if (nargout > 1)
+    varargout = {x, y};
+  else
+    varargout = {y};
+  endif
+
+endfunction
+
+
+%!demo
+%! clf;
+%! fplot (@humps, [0, 2]);
+%! title ("humps() function");
+
+## tests
+## value checks
+%!assert (humps (0), 88/17, 10*eps)
+%!assert (humps (1), 16, 10*eps)
+%!assert (humps (-1), -6376/1241, 10*eps)
+%!assert (humps (), [88/17, 16106/1769, 263/17, 82802/3133, 2432/53, ...
+%!   2818/37, 193/2, 10538/137, 1376/29, 36434/1261, 19, 5258/377,  ...
+%!   152/13, 24562/2173, 421/34, 250/17, 232/13, 1762/85, 803/37,   ...
+%!   58354/2941, 16], 1000*eps)
+
+## vector checks
+%!assert (humps ([0, 1]), [88/17, 16], 10*eps)
+%!assert (humps ([0, 1]'), [88/17, 16]', 10*eps)
+%!assert (humps ([0, 1; 1, 0]'), [88/17, 16; 16, 88/17]', 10*eps)
+
+## array checks
+%!assert (humps (repmat (eye (2), 1, 1, 2)), repmat ([16, 88/17; 88/17, 16], ...
+%! 1, 1, 2), 10*eps)
+
+## other checks
+%!assert (humps (NaN), NaN)
+%!assert (humps ([]), [])
+
+## errors
+%!error humps (1,3)
\ No newline at end of file
diff -r 0d4107676ddf -r 5ae2b8c6a231 scripts/optimization/module.mk
--- a/scripts/optimization/module.mk	Sun Feb 05 10:00:19 2017 -0800
+++ b/scripts/optimization/module.mk	Wed Feb 08 09:01:27 2017 -0500
@@ -13,6 +13,7 @@
   scripts/optimization/fsolve.m \
   scripts/optimization/fzero.m \
   scripts/optimization/glpk.m \
+  scripts/optimization/humps.m \
   scripts/optimization/lsqnonneg.m \
   scripts/optimization/optimget.m \
   scripts/optimization/optimset.m \
