JAKEF is a precompiler that analyses a given Fortran77 source code for 
the evaluation of a scalar or vector function and then generates an
expanded Fortran subroutine that simultaneously evaluates the gradient
or Jacobian respectively. For scalar functions the ratio between the 
run-time of the resulting gradient routine and that of the original
evaluation routine is never greater than a fixed bound of about five. 
The storage requirement may be considerable as it is also proportional 
to the run-time of the original routine. Since no differencing is done
the partial derivative values obtained are exact up to round-off errors. 
    The user must prepare the input code subject
to some restrictions and nominate the dependent and independent 
variables by a CONSTRUCT statement as described in the doc file. 
Subsequently the precompiler JAKEF may be called through the interface
routine JAKED1(IWA,LIWA,CWA,LCWA), where the lengths LIWA and LCWA of 
the integer and character work arrays IWA and CWA must be chosen 
sufficiently large. The source code must be supplied through the input 
unit NREAD which is set to 5 in JAKED1. 
    If the precompilation is completed successfully JAKEF produces an 
extended Fortran77 subroutine whose name is that of the original code 
appended with a "J", e.g. EVAL(X,F) is expanded to 
EVALJ(X,F,GRAD,RFS,IFS,LFS). The extended Fortran routine can then be 
compiled into object code and called within a numerical scheme, 
whereever the function and its partial derivatives need be evaluated at
certain values of the independent variables, e.g. X. During the 
evaluation the extended evaluation routine calls on auxcilliary routines
EMIT0, EMIT1, EMIT2, SPCOPY, SPGRAD, SPINIT, and SERRM or their double 
precision equivalents DMIT0, DMIT1, DMIT2, DPCOPY, DPGRAD, DPINIT, and 
DERRM. Therefore either suite of seven subroutines must also be compiled
and linked into the main program. 
    The precompilation may fail due to insufficient work space or the 
violation of some restriction on the input code. In either case JAKEF 
prints appropriate if not very convenient diagnostics. Even if generated
successfully the extended evaluation routine may not execute properly
due to arithmetic contingencies or insufficient storage. The latter
problem can be fixed by enlarging the common lenght LFS of the real 
and integer arrays RFS and IFS in the call to the extended routine.
    
	All subroutines comprising the precompiler are contained in the
file JAKEFF. The other Fortran file SUPPORTF contains: 

SAMPLE        Main program calling JAKEF via the interface JAKED1.

SWATS         Single precision version of Watson scalar function.
              (For comparison the result SWATSJ of a successfull 
               precompilation with JAKEF is included as comment)

DCHEB         Double precision version of chebyquad vector function.
              (For comparison the result DCHEBJ of a successfull 
              precompilation with JAKEF is included as comment)

EMIT0         Runtime support library for single precision calculation.
EMIT1
EMIT2
SPCOPY
SPGRAD
SPINIT
SERRM

DMIT0         Runtime support library for double precision calculation.
DMIT1
DMIT2
DPCOPY
DPGRAD
DPINIT
DERRM

For precompilation the user only needs to feed his source code 
(e.g. SWATS) into the input stream of the executable program obtained
by compiling SAMPLE together with the contents of JAKEFF. The resulting
expanded routine (e.g. SWATSJ) can then be called from any other FORTAN
provided the appropriate suite of support routines (i.e. EMIT0..SERRM
or DMIT0..DERRM) is included in the compilation.

A. Griewank, Argonne National Laboratory, griewank@mcs.anl.gov, 12/1/88.