
NAME
vemfre  Frechet derivative check
SYNOPSIS
 CALL VEMFRE(

T, LU, U, UT, LIVEM, IVEM, LRVEM, RVEM, LNEK, NEK,
LRPARM, RPARM, LIPARM, IPARM, LDNOD, DNOD, LRDPRM, RDPARM,
LIDPRM, IDPARM, LNODN, NODNUM, LNOD, NOD, LNOPRM, NOPARM,
LBIG, RBIG, IBIG, MASKL, MASKF, USERL, USERF)
 INTEGER

LU, LIVEM, LRVEM, LNEK, LRPARM, LIPARM, LDNOD, LRDPRM,
LIDPRM, LNODN, LNOPRM, LBIG
 LOGICAL

MASKL(NK,NK,NGROUP), MASKF(NK,NK,NGROUP)
 INTEGER

IVEM(LIVEM), NEK(LNEK), IPARM(LIPARM), DNOD(LDNOD),
IDPARM(LIDPRM), NODNUM(LNODN), IBIG(*)
 DOUBLE PRECISION

T, U(LU), UT(LU), RVEM(LRVEM), RPARM(LRPARM), RDPARM(LRDPRM),
NOD(LDNOD), NOPARM(LNOPRM), RBIG(LBIG)
 EXTERNAL

USERL, USERF
PURPOSE
vemfre is a subroutine to test whether the bilinear form L defined in
USERL (see userl) is the Frechet derivative of the linear
form F defined in USERF (see userf). It compares the
the difference quotient and the entries of the user routines. The numerical
check cannot exactly answer the question of the exactness of
the Frechet derivative, but it can give useful hints where errors
may have ocurred. vemfre can be applied to steady problems
(see veme02) and nonsteady problems
(see vemp02). Additionally the settings of MASKF and
MASKL and the symmetry of the bilinear form is tested. So
vemfre can also be used to check the masks for the linear solvers,
see veme00.
ARGUMENTS
 T double precision, scalar, input, global

Real number (e.g. current time).
 LU integer, scalar, input, local

Length of the solution vectors U and UT,
LU >=NK*NDEG.
 U double precision, array: U(LU), input, local

The value of an input solution at the geometrical nodes.
U(NDEG*(j1)+i) is the value of the jth component at the
geometrical node i, where i refers to the numbering on the process, see
vemdis. U should be created by a random process.
 UT double precision, array: UT(LU), input, local

The value of the derivative of input solution with respect of T
at the geometrical nodes.
UT(NDEG*(j1)+i) is the value of the jth component at the
geometrical node i, where i refers to the numbering on the process, see
vemdis. U should be created by a random process. If
PARAB=0, UT is not used and U can be also handed over
for UT.
 LIVEM integer, scalar, input, local

Length of the integer information vector,
LIVEM>= MESH+ NINFO.
 IVEM integer, array: IVEM(LIVEM), input/output, local/global

Integer information vector.
 (1)=MESH, input, local

Start address of the mesh informations in IVEM,
MESH>203+ NPROC.
 (2)=ERR, output, global

Error number.
0  program terminated without error. 
81  incorrect masks. 
82  incorrect Frechet derivatives. 
83  illegal element volume. 
90  LBIG is too small. 
95  IVEM, RVEM or U is too small. 
99  fatal error.   (5)=NIVEM, output, local

Used length of IVEM.
 (6)=NRVEM, output, local

Used length of RVEM.
 (90)=LOUT, input, local

Unit number of the standard output file, normally 6.
 (91)=OUTCNT, input, local

Output control flag.
0  only error messages are printed 
>0  in addition a protocol is printed. OUTCNT defective Frechet derivatives are printed. 
 (92)=PARAB, input, global

Indicates the test case.
0  steady case (veme00, veme02). 
1  nonsteady case (vemp02), the Frechet derivative with respect to U is checked. 
2  nonsteady case (vemp02), the Frechet derivative with respect to UT is checked. 
 (200)=NPROC, input, global

Number of processes, see combgn.
 (201)=MYPROC, input, local

Logical process id number, see combgn.
 (202)=NMSG, input/output, global

Message counter. The difference of the input and the output value
gives the number of communications during the vemfre call.
 (204)=TIDS(1), input, global

Begin of the list TIDS which defines the mapping of the
logical process ids to the physical process ids. See combgn.
 (MESH), input, local

Start of mesh informations, see mesh.
 LRVEM integer, scalar, input, local

Length of the real information vector,
LRVEM>=20.
 RVEM double precision, array: RVEM(LRVEM), input/output, local/global

Real information vector.
 (2)=EPS, output, local

Smallest positive number with 1.+EPS>1.
 (4)=DU, input, local

U and DUDX (or UT and DUTDX) are perturbed by the increment DU,
normally 1.D4. If DU=0, the test of the Frechet derivatives is skipped
(use in the case of linear problems).
 LNEK integer, scalar, input, local

Length of the element array.
 NEK integer, array: NEK(LNEK), input, local

Array of the elements, see mesh.
 LRPARM integer, scalar, input, local

Length of the real parameter array.
 RPARM double precision, array: RPARM(LRPARM), input, local

Real parameter array, see mesh.
 LIPARM integer, scalar, input, local

Length of the integer parameter array.
 IPARM integer, array: IPARM(LIPARM), input, local

Integer parameter array, see mesh.
 LDNOD integer, scalar, input, local

Length of the array of the Dirichlet nodes.
 DNOD integer, array: DNOD(LDNOD), input, local

Array of the Dirichlet nodes, see mesh.
 LRDPRM integer, scalar, input, local

Length of the real Dirichlet parameter array.
 RDPARM double precision, array: RDPARM(LRDPRM), input, local

Array of the real Dirichlet parameters, see mesh.
 LIDPRM integer, scalar, input, local

Length of the integer Dirichlet parameter array.
 IDPARM integer, array: IDPARM(LIDPRM), input, local

Array of the integer Dirichlet parameters, see mesh.
 LNODN integer, scalar, input, local

Length of the array of the id numbers of the geometrical nodes.
 NODNUM integer, array: NODNUM(LNODN), input, local

Array of the id numbers of the geometrical nodes, see mesh.
 LNOD integer, scalar, input, local

Length of the array of the coordinates of the geometrical nodes.
 NOD double precision, array: NOD(LNOD), input, local

Array of the coordinates of the geometrical nodes, see mesh.
 LNOPRM integer, scalar, input, local

Length of the array of the node parameters.
 NOPARM double precision, array: NOPARM(LNOPRM), input, local

Array of the node parameters, see mesh.
 LBIG integer, scalar, input, local

Length of the real work array. The needed length of LBIG
depends on the given mesh. A minimal length of LBIG cannot be
given. It should be as large as possible.
 RBIG double precision, array: RBIG(LBIG), work array, local

Real work array.
 IBIG integer, array: IBIG(*), work array, local

Integer work array, RBIG and IBIG have to be defined
by the EQUIVALENCE statement.
 MASKL logical, array: MASKL(NK,NK,NGROUP), input

If MASKL(COMPV,COMPU,G)=true, the COMPVth component of the test
function couples with the COMPUth component of the solution in the bilinear
form L over the elements in the group G.
 MASKF logical, array: MASKF(NK,NGROUP), input

If MASKF(COMPV,G)=true, the COMPVth component
of the test function gives a contribution to the linear
form F over the elements in group G.
 USERL external

Name of the subroutine in which the coefficients of the bilinear form L
are described, see userl. In the cases of DU>0 and
PARAB=0,1, USERL defines the Frechet derivative of F
with respect to U. In the case of DU>0 and
PARAB=2, USERL defines the Frechet derivative of F
with respect to UT.
 USERF external

Name of the subroutine in which the coefficients of the
linear forms F are described, see userf.
USAGE
vemfre is a programming tool and so it should only be used in the
development phase of a program. If you are certain that your masks and
Frechet derivatives are correct, you should eliminate the vemfre
call from your program.
veme00
vemfre can be used to check the entries of the masks. Set PARAB=0
and DU=0. USERL and USERF and are interpreted as
USERL and USERF in the veme00 call. Therefore
MASKL is MASKL of veme00 and MASKF
is MASKF of veme00. U and UT may be undefined.
veme02
vemfre checks the masks and the Frechet derivative of the linear
form. Set PARAB=0 and DU>0. USERL and USERF are
interpreted as USERL and USERF in the veme02
call. MASKL is MASKL of veme02
and MASKF is MASKF of veme02. U has to be
specified (e.g. by a random process) and UT equals U.
vemp02
vemfre checks the masks and the Frechet derivative of the linear
form. It has to be called twice with DU>0. Always MASKL is equal to
MASKL of vemp02 and MASKF is equal to MASKF of
vemp02. In the
first call the derivative of the linear form with respect to the
solution U is checked (set PARAB=1). USERL and
USERF are interpreted as USERL and USERF in the
vemp02 call. In the second call the derivative of the linear form
with respect to the Tderivative UT of the solution is checked
(set PARAB=2). USERL and USERF are interpreted as
USERK and USERF in the vemp02 call. U
and UT have to be specified (e.g. by a random process).
EXAMPLE
See vemexamples.
METHOD
The solution vector U (and UT for PARAB>0) is interpolated
at the geometrical nodes (the proposal mesh is not used in this routine). The
interpolation polynomial and its derivatives with respect to
the space directions are evaluated at the center points of the
elements. The results of the routines USERF for the linear
form and USERL for the Frechet derivative are compared with
the mask entries. Additionally the symmetry of the coefficients of
the Frechet derivative is checked. If DU>0, U (or its Tderivative)
is perturbed by the increment DU. From the results of USERF
for this perturbed data, approximations for the coefficients of
the Frechet derivative are computed by the difference coefficients. The
results of USERL are accepted if they are very close
to the approximations.
RESTRICTIONS
vemfre checks the masks and the Frechet derivative numerically. The
results depend on the entries in U, UT
and the step size DU. We recommend to select DU=1.D4,
but in some problems another selection may be better. Additionally
it could happen that vemfre wrongly indicates to set a mask of a group
to '.false.' although there is a coupling or a contribution. This
occurs if U or UT equals zero or is constant on the manifold described
by the group. In this case you should change your input solution.
SEE ALSO
VECFEM, vemcompile, vemrun, vemhint,
mesh, vemexamples, vemdis,
userf, usrfu, userl, vemdis.
REFERENCES
[FAQ], [THEOMAN], [P_MPI].
COPYRIGHTS
Program by L. Grosz, C. Roll, 19911996.
Copyrights by Universitaet Karlsruhe 19891996.
Copyrights by Lutz Grosz 1996.
All rights reserved. More details see VECFEM.
by L. Grosz, Auckland , 11. June, 2000.
