c-----------------------------------------------------------------------
c
c.....(c) Victor Luana Cabal & Miguel Alvarez Blanco, May. 29, 1993
c Grupo de Quimica Cuantica
c Departamento de Quimica Fisica y Analitica
c Universidad de Oviedo, 33007-Oviedo, Spain.
c
c-----------------------------------------------------------------------
c
c HISTORY:
c
c First version (1.0): (May 29, 1993) VLC & MAB
c
c Revision (1.1): (Jun 11, 1993) MAB & VLC
c Improved control in CRITIC. Added optional Powell update for the
c hessian. Allowed entering function, gradient and hessian for the
c starting point.
c
c-----------------------------------------------------------------------
c
c.....navigator -
c searches for specific critical points of a scalar function of
c several variables.
c
c The function must be provided, at any point
c requested by the algorithm, by means of an external procedure.
c The gradient and hessian at any point may either be returned
c by the external procedure or be numerically determined by
c special navigator routines. Of course, an analytical gradient
c and hessian provided by the external procedure can be far more
c efficient and numerically more stable.
c
c Navigator has been designed as a driver program working
c in unix environments. The programs performs system calls to run
c the external procedure, mechanism that adds some time to the
c computation, but represents a very flexible method easily adapted
c to many different tasks.
c
c.....Mechanism for using navigator:
c
c (navigator data) ----> NAVIGATOR ----> EXTERNAL_PROCEDURE
c ^ |
c | |
c | v
c (file with the func., gradient & hessian values)
c
c Navigator transmits the variable values as parameters to the
c external procedure. This procedure returns the information
c contained in a file. The internal design of the external
c procedure is arbitrary from the navigator viewpoint.
c
c-----------------------------------------------------------------------
c
c.....How to use navigator: navigator [input [output]]
c
c Input is read from stdin when a file name is not given as the
c first parameter. Output is send to the stdout when a file name
c is not given as the second parameter.
c
c-----------------------------------------------------------------------
c
c.....Input data:
c
c Rec #1 (a) : Function_name
c Name of the external procedure that evaluates the function to
c analyze.
c
c Rec #2 (a) : File_name
c File where the external procedure prints the function properties.
c
c Rec #3 (a) : title
c Run title.
c
c Rec #4 (a,i) : der_type, order
c Meaning of the der_type possible values:
c 'numerical' ... gradient and hessian will be computed numerically
c using an iterated Richardson algorithm based on
c a symmetric first-order approach to the limit.
c The external procedure should only return the
c function value at the points requested by the
c algorithm.
c 'analytical' .. gradient and hessian will be returned by the
c external procedure.
c 'powell' ...... the gradient will be numerically determined, but
c the hessian will be approached by the Powell
c update formula. The external function only has to
c return the function value at given points.
c The order parameter has only sense for the 'powell' option. Order
c possible values are:
c 1 ............. the first hessian will be computed numerically.
c Powell update will be used for the next points.
c Gradient is obtained numerically at every step.
c 2 ............. same as 1, but the diagonal elements of the
c hessian will be computed numerically at every
c point. Powell update is used only for the
c nondiagonal elements of the hessian.
c This should add not much time, as the gradient
c and diagonal elements of the hessian are obtained
c upon the same points.
c 3 ............. the hessian is started as a unit matrix. The
c method proceeds as in 1 for the next points.
c *NOTE* The input gradient and hessian, if given, will be used no
c matter the value given to 'order' (See below how to enter gradient
c and hessian at the starting point).
c
c Rec #5 (*) : nvar
c Total number of variables of the scalar function.
c
c IF (der_type .in. ('numerical', 'powell')) THEN
c
c DO I = 1, nvar
c Rec #6.i (*) : var_name(i), var_value(i),
c var_min(i), var_max(i),
c hinic(i)
c ENDDO
c var_name() ... name for the variable.
c var_value() .. starting value for the variable.
c var_min() .... minimum value allowed for the variable.
c var_max() .... maximum value allowed for the variable.
c hinic() ...... in the case of numerical computation of the
c derivatives, this is the initial step for
c varying each variable. This value should not
c be very small, otherwise the Richardson iterative
c algorithm has no space to work. Some ten percent
c of the typical value of the variable use to
c be appropriate. In a strict sense, hinic() should
c be optimized up to the value that gives the
c best convergence for the derivatives.
c
c Rec #7 (*) : prec
c precision required in the calculation of the derivatives.
c
c ELSE IF (der_type .eq. 'analytical') THEN
c
c DO I = 1, nvar
c Rec #6.i (*) : var_name(i), var_value(i),
c var_min(i), var_max(i)
c ENDDO
c
c ENDIF
c
c Rec #8 (*) : nneg, grdconv, iconv, h2, istep, ifirst, maxpath, nprt
c nneg .... number of negative eigenvalues of the critical point
c being searched.
c grdconv . convergence asked for in the modulus of the gradient.
c iconv ... relative (iconv=0) or absolute (=1) error will be used
c to determine the convergence.
c h2 ...... starting step for the walk path algorithm. The meaning
c of this parameter depends upon istep.
c istep ... -1 ---> use h2 as a fixed step for all the path.
c 0 ---> use authomatic procedures to start h2 and
c change its values at each step. The difference
c varmin()-var_max() will influence the starting
c value.
c 1 ---> use h2 as the first step, but change it
c authomatically at each step.
c ifirst .. 0 ----> the direction of the first step will be
c determined upon the gradient and the hessian
c eigenvalues at the starting point.
c 1 ----> only the hessian eigenvalues will determine
c the direction for the first step. Use this
c method when starting on a critical point.
c maxpath . max number of steps that will be allowed in the search
c for the target point. This number must be less or equal
c than the MPATH parameter.
c nprt .... amount of information to be printed:
c 0 ----> input and final results (This includes the
c path and the last point found).
c 1 ----> function value, gradient and hessian at every
c visited point and wether the point is accepted
c or rejected.
c 2 ----> 1 plus the hessian eigenvalues and vectors at
c every point.
c 3 ----> 2 plus the numerical derivatives (if any).
c 4 ----> 3 plus the function value at every external
c point requested either by the CRITIC algorithm
c or the numerical derivative rotines.
c
c Rec #9 (*) : istart
c 1 ....... the function, gradient and hessian in the starting point
c is known in advance and will be entered in the next
c cards.
c 0 ....... otherwise
c
c IF (istart .eq. 1) THEN
c
c Rec #10 (*) : startfunc
c Value of the function in the starting point.
c
c Rec #11 (*) : (startg(i), i = 1, nvar)
c Value of the gradient in the starting point.
c
c Rec #12 (*) : (starth(i), i = 1, (nvar*(nvar+1))/2 )
c Value of the hessian in the starting point. Enter the lower
c triangle hessian elements in supervector order.
c
c ENDIF
c
c-----------------------------------------------------------------------
c
c.....Requirements of the external procedure:
c
c The function to analyze is supossed to be evaluated by an external
c procedure, which will be run in a subshell by means of the order:
c
c Function_name var_value(1) var_value(2) ... var_value(nvar)
c
c The results required will be returned in a file. When navigator
c is run in 'analytical' mode, the file must contain:
c (a) the function value in the first line
c (b) the gradient elements, an element per line
c (c) the lower diagonal elements for the hessian, one element
c per line, in the order H11, H12, H22, H13, H23, H33, ...
c When navigator is run in 'numerical' or 'powell1' mode, however,
c the results file only has to contain the function value.
c
c The precision used to evaluate the function will influence the
c maximum precision attainable in the derivatives.
c
c-----------------------------------------------------------------------