DEFINITION MODULE OptimLib3;

  (*------------------------------------------------------------------------*)
  (* Minimirungsroutinen fuer Funktionen mit bekannter 1. Ableitung.        *)
  (* Minimization of a function of several variables with derivative        *)
  (*------------------------------------------------------------------------*)
  (* Please not that there is not OptimLib2 at the moment, this is reserved *)
  (* for Michael Powells "bobyqa" routine (in preparation, a goto free      *)
  (* Fortran 90 version is already available).                              *)
  (*------------------------------------------------------------------------*)
  (* Implementation : Michael Riedl                                         *)
  (* Licence        : GNU Lesser General Public License (LGPL)              *)
  (*------------------------------------------------------------------------*)

  (* $Id: OptimLib3.def,v 1.4 2018/04/26 10:17:19 mriedl Exp mriedl $ *)

FROM Deklera  IMPORT PMATRIX;
FROM LMathLib IMPORT Funktion1,FunktionN;


TYPE  TGradient = PROCEDURE(VAR ARRAY OF LONGREAL,
                                CARDINAL,
                            VAR ARRAY OF LONGREAL);

      (*----------------------------------------------------------------*)
      (* A procedure of type "TGradient" calculates the gradient of a   *)
      (* given function of N parameters at point(s) X and returns the   *)
      (* result in vector G and will be called as "Gradient(X,N,G)"     *)
      (*----------------------------------------------------------------*)

PROCEDURE MinInDer(VAR a,b  : LONGREAL;
                       f    : Funktion1;
                       df   : Funktion1;
                       ftol : Funktion1;
                   VAR x,y  : LONGREAL;
                   VAR xmin : LONGREAL;
                   VAR cnt  : CARDINAL);

          (*----------------------------------------------------------------*)
          (* MinInDer delivers the calculated  minimum value of the         *)
          (* function, defined by f(x), on the interval with end points     *)
          (* a and b. The function is approximated by a cubic as given by   *)
          (* Davidon [1], the structure is similar to the structure of the  *)
          (* program given by Brent [2]                                     *)
          (*                                                                *)
          (* The meaning of the formal parameters is:                       *)
          (*                                                                *)
          (*   a,b  : The start and end point of the interval on which the  *)
          (*          function has to be minimized                          *)
          (*   fx   : the function is given by the actual parameter fx      *)
          (*          which depends on x                                    *)
          (*   dfx  : the derivative of the function is given by the actual *)
          (*          parameter dfx which depends on x, fx and dfx are      *)
          (*          evaluated successively for a certain value of x       *)
          (*   tolx : the tolerance is given by the actual parameter tolx,  *)
          (*          which may depend on x, a suitable tolerance function  *)
          (*          is: abs(x) * re + ae, where re is the relative        *)
          (*          precision desired and ae is an absolute precision     *)
          (*          which should not be chosen equal to zero.             *)
          (*   x    : On exit the calculated approximation of the position  *)
          (*          of the minimum                                        *)
          (*   y    : On exit a value such that abs(x - y) <= 3*tol(x)      *)
          (*   xmin : On exit the function value at position x              *)
          (*   cnt  : On exit the number of function evaluations            *)
          (*                                                                *)
          (* Data and results:                                              *)
          (*                                                                *)
          (* The user should be aware of the fact that the choice of tol(x) *)
          (* may highly  affect the behaviour of the algorithm, although    *)
          (* convergence to a point for which the given function is         *)
          (* minimal on the given interval is assured. The asymptotic       *)
          (* behaviour will usually be fine as long as the numerical        *)
          (* function is strictly delta-unimodal on the given interval      *)
          (* (see [1]) and the tolerance function satisfies                 *)
          (* tol(x) >= delta, for all x in the given interval, let the      *)
          (* value of dfx at the begin and end point of the initial         *)
          (* interval be denoted by dfa and dfb, respectively, then,        *)
          (* finding a global minimum is only guaranteed if the function    *)
          (* is convex and dfa <= 0 and dfb >= 0. If these conditions are   *)
          (* not satisfied, then a local minimum or a minimum at one of     *)
          (* the end points might be found.                                 *)
          (*                                                                *)
          (* [1] Brent, R.P.: "Algorithms for minimization without          *)
          (*     derivatives": Chap. 5: Prentice Hall (1973)                *)
          (* [2] Davidon, W.C.: "Variable metric methods for minimization": *)
          (*     A.E.C. Research and Development Report ANL-5990            *)
          (*     (Rev. TID-4500, 14th ed.) (1959)                           *)
          (*----------------------------------------------------------------*)
          (* This routine is a translation of the Algol 60 procedure        *)
          (* mininder from the NUMAL Algol library (Stichting CWI)          *)
          (*                                                                *)
          (* Diese Routine ist eine Modula-2 Uebersetzung der Algol 60      *)
          (* Prozedur "mininder" aus der NUMAL Numerical Algol library      *)
          (* (Stichting CWI) Teil 2 (numal5p2)                              *)
          (*----------------------------------------------------------------*)

PROCEDURE VMMin(    Func      : FunktionN;
                    n         : CARDINAL;
                    Gradient  : TGradient;
                VAR X         : ARRAY OF LONGREAL;
                VAR Bvec      : ARRAY OF LONGREAL;
                VAR Fmin      : LONGREAL;
                VAR funcount  : CARDINAL;
                VAR gradcount : CARDINAL;
                VAR iFehl     : INTEGER);

          (*----------------------------------------------------------------*)
          (* Variable metric function minimiser                             *)
          (*                                                                *)
          (* Unlike Fletcher-Reeves no quadratic interpolation is used      *)
          (* since the search is often approximately a Newton step          *)
          (*                                                                *)
          (*   Func      : Function of n variables to be minimized          *)
          (*   n         : number of variables                              *)
          (*   Gradient  : Gradient of function to be minimized             *)
          (*   X         : vector of final function parameters              *)
          (*   Bvec      : vector of initial function parameters            *)
          (*   Fmin      : value of Funx(X,n)                               *)
          (*   funcount  : number of evaluations of Func                    *)
          (*   gradcount : number of evaluations of Gradient                *)
          (*   iFehl     :  -1 = Function cannot be evaluated at initial    *)
          (*                     parameters                                 *)
          (*                                                                *)
          (* This routine is an adopted version of the Pascal routine       *)
          (* vmmin found in ref [2]. It is published under the GPL with     *)
          (* written permission of the author.                              *)
          (*                                                                *)
          (* [1] Fletcher, R.; "A new approach to variable metric           *)
          (*     algorithms", Computer Journal, 13/3 pp. 317-322 (1970)     *)
          (* [2] Nash, J.C.; "Compact Numerical Methods for Computers",     *)
          (*     Second Edition, Adam Hilger, Bristol, UK (1990)            *)
          (*----------------------------------------------------------------*)

PROCEDURE CGMin(    Func      : FunktionN;
                    n         : CARDINAL;
                    Gradient  : TGradient;
                VAR X         : ARRAY OF LONGREAL;
                VAR Bvec      : ARRAY OF LONGREAL;
                VAR Fmin      : LONGREAL;
                VAR funcount  : CARDINAL;
                VAR gradcount : CARDINAL;
                VAR intol     : LONGREAL;
                    setstep   : LONGREAL;
                    methode   : CARDINAL;
                VAR iFehl     : INTEGER);

          (*----------------------------------------------------------------*)
          (* Conjugate gradients function minimiser                         *)
          (*                                                                *)
          (*   Func      : Function of n variables to be minimized          *)
          (*   n         : number of variables                              *)
          (*   Gradient  : Gradient of function to be minimized             *)
          (*   X         : vector of final function parameters              *)
          (*   Bvec      : vector of initial function parameters            *)
          (*   Fmin      : value of Funx(X,n)                               *)
          (*   funcount  : number of evaluations of Func                    *)
          (*   gradcount : number of evaluations of Gradient                *)
          (*   intol     : Tolerance for the evaluation of Func.            *)
          (*               Tolerance used is then tol = ntol*n*sqrt(intol)  *)
          (*               If Func(X,n) is not lowered by more than tol     *)
          (*               within one cycle of the minimization process     *)
          (*               the process is regarded as beeing converged.     *)
          (*               Set the tolerance negative to indicate that      *)
          (*               procedure must obtain an appropriate value.      *)
          (*   setstep   : steplength saving factor                         *)
          (*                                                                *)
          (*   methode   :   1 = Fletcher Reeves                            *)
          (*                 2 = Polak Ribiere                              *)
          (*                 3 = Beale Sorenson                             *)
          (*                                                                *)
          (*   iFehl     :  -1 = Function cannot be evaluated at initial    *)
          (*                     parameters                                 *)
          (*               -99 = Wrong parameter "methode"                  *)
          (*                99 = At least one result is either INF of NAN   *)
          (*                                                                *)
          (* This routine is an adopted version of the Pascal routine       *)
          (* cgmin found in ref [2]. It is published under the GPL with     *)
          (* written permission of the author.                              *)
          (*                                                                *)
          (* [1] Fletcher,R; Reeves,C.M.; Computer Journal 7/7,             *)
          (*     pp. 149-154 (1964)                                         *)
          (* [2] Nash, J.C.; "Compact Numerical Methods for Computers",     *)
          (*     Second Edition, Adam Hilger, Bristol, UK (1990)            *)
          (*----------------------------------------------------------------*)

END OptimLib3.
