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.