/*
  File name: simplex.h
  Created by: Ljubomir Buturovic
  Created: 07/02/2004
  Purpose: declarations for simplex(), the implementation of
  Nelder-Mead simplex algorithm for function optimization without
  derivatives.
*/

/*
  Copyright 2004 Ljubomir J. Buturovic

  Permission is hereby granted, free of charge, to any person
  obtaining a copy of this software and associated documentation files
  (the "Software"), to deal in the Software without restriction,
  including without limitation the rights to use, copy, modify, merge,
  publish, distribute, sublicense, and/or sell copies of the Software,
  and to permit persons to whom the Software is furnished to do so,
  subject to the following conditions:

  The above copyright notice and this permission notice shall be
  included in all copies or substantial portions of the Software.

  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
  BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
  ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  SOFTWARE.
*/

#include "crit.h"

/*
  simplex() returns minimum value of function 'func' of 'len'
  variables, using simplex method of Nelder-Mead. On input, 'smx' is
  the (len+1)*len matrix (array of len+1 pointers to len-long arrays)
  representing the initial simplex; 'fval' are the corresponding len+1
  values of 'func'; 'itmax' is the maximum allowed number of
  iterations; 'parameters' is a pointer to a structure used to pass
  additional arguments to the criterion function. On output, 'smx'
  contains the simplex at time of termination. If the algorithm
  converged (as opposed to reaching 'itmax'), all points in 'smx' will
  have function values within 'ftol' of each other.  'fval' has the
  corresponding function values and 'iter' the number of iterations it
  took to terminate.

  The signature of func() must be:

  float func(float *x, int n, int iteration, void *parameters, int *errc);
  
  Here, 'x' is the n-dimensional point at which the function is
  evaluated and 'n' is length of the vector.  'parameters' is a
  pointer to the structure used to pass additional arguments to
  func().  'iteration' is the current iteration, set by simplex(), and
  'errc' contains the error code set by func().  In case of successful
  evaluation, func() must set *errc to 0, and non-zero otherwise.
  
  On success, simplex() returns the minimum value, sets 'iter' to the
  number of iterations, and sets 'errc' to 0; on error, it returns
  MAX_FLOAT and sets error code in 'errc'. The error codes are EINVAL
  for bad arguments, malloc() error codes, or function evaluation
  error code as set by func().

  The implementation follows: Margaret H. Wright, Optimization Methods
  For Base Station Placement In Wireless Applications, Proceedings of
  1998 Vehicular Technology Conference, Vol. 89, pp. 11513--11517,
  1998.
*/
float simplex(float **smx, int len, float *fval, crit_func *func,
	      void *parameters, int itmax, float ftol, int *iter,
	      int *errc);