INTERFACE GradMin;

PROCEDURE Minimize(
    f: GoalFunc;
    VAR x: ARRAY OF REAL;         (* In: starting point, Out: best point found. *)
    VAR y: REAL;                  (* Out: value of "f" at optimum. *)  
    VAR dy: ARRAY OF REAL;        (* Out: gradient of "f" at "x". *)
    maxCalls: CARDINAL;           (* Maximum number of calls to "f". *)
    minStep: REAL := 1.0e-30;     (* Minimum step size. *)
    maxStep: REAL := 1.0e+30;     (* Maximum step size. *)
    report: ReportProc := NIL;       (* Called when a new minimum is found. *)
    normalize: NormalizeProc := NIL; (* Called to modify point before applying "f". *)
    verbose: BOOLEAN := FALSE;       (* TRUE to mumble while working. *)
    Alpha: REAL := 2.0;    (* Step lengthening factor. *)
    Beta: REAL := 0.5;     (* Step shortening factor. *)
    Gamma: REAL := 1.0;    (* Velocity steering factor. *)
  );
  (* 
    Minimizes "f" by a straightforward gradient-descent method,
    with step shrink/expand factors Alpha, Beta.
    
    The client must initialize the array "x" with the starting point
    for the descent.
    
    If "report" is not NIL, it is called whenever a new minimum is found.
    
    If "normalize" is not NIL, it is applied to every generated point,
    before evaluating "f" on it.  This feature allows minimization inside 
    bounded domains, or over curved subspaces of "R^N".

    The procedure stops when "report" returns TRUE, or after
    "maxCalls" calls to "f", or if the gradient becomes zero, 
    or if the procedure fails to find a lower point by searching along the 
    gradient direction.
    
    Upon return return, "x" will be the best point found, and "y" and "dy" 
    will be the value and gradient of "f" at "x".
  *)
  
TYPE 
  GoalFunc = PROCEDURE (READONLY x: ARRAY OF REAL; VAR y: REAL; VAR dy: ARRAY OF REAL);
  ReportProc = PROCEDURE (READONLY x: ARRAY OF REAL; y: REAL; READONLY dy: ARRAY OF REAL): BOOLEAN;
  NormalizeProc = PROCEDURE (VAR x: ARRAY OF REAL);

END GradMin.