\inputencoding{utf8}
\HeaderA{neldermead.algo}{Nelder-Mead Algorithm}{neldermead.algo}
\aliasA{boxlinesearch}{neldermead.algo}{boxlinesearch}
\aliasA{neldermead.box}{neldermead.algo}{neldermead.box}
\aliasA{neldermead.fixed}{neldermead.algo}{neldermead.fixed}
\aliasA{neldermead.interpolate}{neldermead.algo}{neldermead.interpolate}
\aliasA{neldermead.storehistory}{neldermead.algo}{neldermead.storehistory}
\aliasA{neldermead.termination}{neldermead.algo}{neldermead.termination}
\aliasA{neldermead.variable}{neldermead.algo}{neldermead.variable}
\keyword{method}{neldermead.algo}
%
\begin{Description}\relax
\code{neldermead.algo} performs an optimization without restart using the
method associated with the \code{method} element of the neldermead object;
\code{neldermead.fixed}, \code{neldermead.variable}, \code{neldermead.box},
\code{boxlinesearch}, \code{neldermead.storehistory},
\code{neldermead.termination}, and \code{neldermead.interpolate} are utility
functions for \code{neldermead.algo}.
\end{Description}
%
\begin{Usage}
\begin{verbatim}
  neldermead.algo(this = NULL)
  neldermead.fixed(this = NULL)
  neldermead.variable(this = NULL)
  neldermead.box(this = this)
  boxlinesearch(this = NULL, n = NULL, xbar = NULL, xhigh = NULL, fhigh = NULL,
                rho = NULL)
  neldermead.storehistory(this = NULL, n = NULL, fopt = NULL, xopt = NULL,
                          xcoords = NULL)
  neldermead.termination(this = NULL, fvinitial = NULL, oldfvmean = NULL,
                         newfvmean = NULL, previousxopt = NULL,
                         currentxopt = NULL, simplex = NULL)
  neldermead.interpolate(x1 = NULL, x2 = NULL, fac = NULL)
\end{verbatim}
\end{Usage}
%
\begin{Arguments}
\begin{ldescription}
\item[\code{this}] A neldermead object.
\item[\code{n}] Number of variables.
\item[\code{xbar}] The centroid.
\item[\code{xhigh}] The high point.
\item[\code{fhigh}] The value of the cost function at \code{xhigh}.
\item[\code{rho}] The reflection factor.
\item[\code{fopt}] The current value of the function at the current optimum point
estimate.
\item[\code{xopt}] The current optimum point estimate.
\item[\code{xcoords}] Matrix of size n x n+1, coordinates of the n+1 vertices
\item[\code{fvinitial}] The initial cost function value.
\item[\code{oldfvmean}] The old cost function value average on the simplex.
\item[\code{newfvmean}] The new cost function value average on the simplex.
\item[\code{previousxopt}] The previous point estimate.
\item[\code{currentxopt}] The current point estimate.
\item[\code{simplex}] The simplex. The best point estimate in the simplex is expected
to be stored at 1, while the worst point estimate in the simplex is expected
to be stored at n+1.
\item[\code{x1}] The first reference point estimate to perform the
interpolation.
\item[\code{x2}] The second reference point estimate to perform the
interpolation. 
\item[\code{fac}] A factor to perform the interpolation.
\end{ldescription}
\end{Arguments}
%
\begin{Details}\relax
\begin{description}

\item[\code{neldermead.fixed}] The simplex algorithm with fixed size simplex.
We implement the following 'rules' of the method of Spendley et al.
\begin{itemize}

\item Rule 1 is strictly applied, but the reflection is done by reflection
of the high point, since we minimize a function instead of maximizing it,
like Spendley.
\item Rule 2 is NOT implemented, as we expect that the function evaluation
is not subject to errors.
\item Rule 3 is applied, i.e. reflection with respect to next to high point.
A shrink step is included, with shrinkage factor sigma.

\end{itemize}


Rule 1. Ascertain the lowest reading y, of yi ... Yk+1
Complete a new simplex Sp by excluding the point Vp corresponding to
y, and replacing it by V* defined as above.

Rule 2. If a result has occurred in (k + 1) successive simplexes, and is not
then eliminated by application of Rule 1, do not move in the direction
indicated by Rule 1, or at all, but discard the result and replace it by a
new observation at the same point.

Rule 3. If y is the lowest reading in So , and if the next observation made,
y* , is the lowest reading in the new simplex S , do not apply Rule 1 and
return to So from Sp . Move out of S, by rejecting the second lowest reading
(which is also the second lowest reading in So).

\item[\code{neldermead.variable}] The original Nelder-Mead algorithm, with
variable-size simplex.
\item[\code{neldermead.box}] The Nelder-Mead algorithm, with variable-size
simplex and modifications by Box for bounds and inequality constraints.
\item[\code{boxlinesearch}] Called by \code{neldermead.box}, i.e. Box's
method. Perform a line search from xbar, on the line (xhigh,xbar). The
reflected point estimate satisfies the following constraints: \begin{itemize}

\item fr < fhigh
\item xr satisfies the bounds constraints
\item xr satisfies the nonlinear positive inequality constraints
\item xr satisfies the linear positive inequality constraints

\end{itemize}

The method is based on projection and scaling toward the centroid.
\item[\code{neldermead.storehistory}] Store the optimization history into the
neldermead object.
\item[\code{neldermead.termination}] Determine if the algorithm must continue
or terminate. The function uses the cost function average in the simplex
instead of the best cost function value. This is because the function
average changes at each iteration. Instead, the best function value has a
step-by-step evolution and may not change between two successive iterations,
leading to a stop of the algorithm.
\item[\code{neldermead.interpolate}] Compute the point estimate xi as an
interpolation between x1 and x2, as follows:  xi = (1+fac)x1 - fac*x2

\end{description}

\end{Details}
%
\begin{Value}
\begin{description}

\item[\code{neldermead.fixed}, \code{neldermead.variable}, and
\code{neldermead.box}] Return the updated neldermead object, containing the
optimum point estimate.
\item[\code{boxlinesearch}] Return a list with the following elements:
\begin{description}

\item[this] The updated neldermead object.
\item[status] TRUE if the search is successful, FALSE otherwise.
\item[xr] The reflected point estimate.
\item[fr] The value of the cost function at \code{xr}.

\end{description}


\item[\code{neldermead.storehistory}] Return the updated neldermead object.
\item[\code{neldermead.termination}] Return a list with the following
elements: \begin{description}

\item[this] The updated neldermead object
\item[terminate] TRUE if the algorithm terminates, FALSE if the algorithm
must continue.
\item[status] The termination status: 'continue', 'maxiter', 'maxfuneval',
'tolf', 'tolx', 'tolsize', 'tolsizedeltafv', 'kelleystagnation',
'tolboxf', 'tolvariance' or the user-defined termination status.

\end{description}


\item[\code{neldermead.interpolate}] Return a new point estimate, i.e. a
column vector.

\end{description}

\end{Value}
%
\begin{Author}\relax
Author of Scilab neldermead module: Michael Baudin (INRIA - Digiteo)

Author of R adaptation: Sebastien Bihorel (\email{sb.pmlab@gmail.com})
\end{Author}
