
VECFEM3 Reference Manual: vembuild
Type: command
NAME
vembuild  builds a FORTRAN source code to solve a steady functional equation by VECFEM
SYNOPSIS
vembuild <workpiece>
PURPOSE
vembuild builds the FORTRAN source code for the solution of a nonlinear functional equation by VECFEM on a mono processor as well as on a parallel computer. The used finite element mesh has to use elements of order two. The source code reads the FEM mesh from a data set, solves the given functional equation and writes specified sets of components of the solution and the condensed error indicator to data sets using a selected output format. A list of the read and written files is created in the file <workpiece>.lst, which can be reformatted to a control file for some postprocessors by vempost. The control parameters are specified in the data set <workpiece>.resource and the functional equation in the data set <workpiece>.equation, see equation. The generated code is in the output file <workpiece>.f. This FORTRAN program can be compiled by vemcompile. vembuild has to be called from the ksh shell.
PARAMETER
Every line in the file <workpiece>.resource contains one statement of the form
<parameter>=<value>
which assigns the value <value> to the parameter <parameter> during the building of the FORTRAN source code. Lines starting with '#' are comment lines. Spaces are insignificant. For <parameter> upper and lowercase letters are equivalent. <parameter> has to be one of the following expressions, where unspecified parameters get the value <default> defined by default=<default>:
 MESH_PREP
 The name of the used preprocessor specifies the format of the mesh input file, default=IDEAS. The elements of the mesh subdivide the domains of integration in the functional which is defined in the data set <workpiece>.equation. Additionally for every component the nodes of the mesh are specified where the Dirichlet condition has to be satisfied. The mesh must only use elements of order two. It has to be continuous, i.e. if the elements used for the subdivision of the volume are reduced to the area, they are the elements for the subdivision of the area itself (the same for the line elements and the point elements). If you use only a few nodes to specify the Dirichlet conditions, you should ensure that there are enough points which are vertices of elements in the mesh. The following values for MESH_PREP are allowed:
 IDEAS  input file is an IDEAS universal file
 The following table shows the allowed element types, see idevem:
domain 
IDEAS elements 
point 
nodal forces of all load sets 
line 
parabolic beam 
area 
thin shell, parabolic triangle 

thin shell, parabolic quadrilateral 
volume 
solid, parabolic tetrahedron 

solid, parabolic wedge 

solid, parabolic brick 
 The nodes where the Dirichlet conditions for component d are prescribed are specified as the xdisplacement in the ith restraint set. The prevalue parameter in the definition of the Dirichlet condition of component d is set to the value of the xdisplacement.
 PATRAN  input file is a PATRAN neutral file
 The following table shows the allowed element types, see patvem:
domain 
PATRAN elements 
point 
nodal forces of all load sets 
line 
BAR/3 
area 
TRI/6 

QUAD/8 and QUAD/9 
volume 
TET/10 

WEDGE/15 

HEX/20 
 The nodes where the Dirichlet conditions for component d are prescribed are specified as the xdisplacements in the constraint set with setid i. The prevalue parameter in the definition of the Dirichlet condition of component d is set to the value of the xdisplacement.
 VECFEM or print  input file is a VECFEM file
 The mesh file has three parts. In the first part the geometrical nodes are specified, in the second part the elements are described and in the third part the Dirichlet conditions are set, see also vemu02. The node coordinates are written to unit UNIT by the following FORTRAN code:
WRITE(UNIT,*) NDEG
DO i=1,NDEG
WRITE(UNIT,*) NODNUM,NOD(1),NOD(2),NOD(3)
ENDDO
 where NDEG is the number of nodes in the mesh and the node with node id NODNUM has the coordinates (NOD(1), NOD(2), NOD(3)). The elements are written to unit UNIT by the following FORTRAN code:
WRITE(UNIT,*) NGROUP
DO k=1,NGROUP
WRITE(UNIT,*) NE,CLASS,FORM,GEOTYP
DO i=1,NE
WRITE(UNIT,*) ELEMID,INDEX,(NEK(j),j=1,GEOTYP)
ENDDO
ENDDO
 where NGROUP specifies the number of different element types and NE the number of elements of type (CLASS, FORM, GEOTYP). ELEMID is the id number of the element, which should be unique. INDEX is an arbitrary integer value, NEK gives the id number of the GEOTYP nodes which describe the element. The following figure shows the allowed elements of order two and the succession of the describing nodes:
domain 
CLASS 
FORM 
GEOTYP 
VECFEM elements 
point 
0 
1 
1 
1 
line 
1 
2 
3 
132 
area 
2 
3 
6 
3
 \
6 5
 \
142 

2 
4 
8 
473
 
8 6
 
152 
volume 
3 
6 
15 
6
/ : \
15 : 14
/ : \
4135
 : 
 12 
 : 
10 3 11
 / \ 
 9 8 
 / \
172 

3 
4 
10 
4
\ \
 \ 10
 \ \
 9 3
 \ / 
8 X 6
 / \ 
 7 \ 
 / \
152 

3 
8 
20 
8197
/ : /:
20 : 18 :
/ : / :
5176 :
 :  :
 16  15
13 : 14 :
 4113
 /  /
 12  10
 / /
192 
 The Dirichlet conditions are written to unit UNIT by the following FORTRAN code:
WRITE(UNIT,*) NK
DO d=1,NK
WRITE(UNIT,*) NDC
DO i=1,NDC
WRITE(UNIT,*) DNOD,prevalue
ENDDO
ENDDO
 where NDC is the number of nodes with Dirichlet conditions for component d. DNOD is the id number of the node where a Dirichlet condition is set, and prevalue is the value for component d at this node.
 MESH_POSTP
 The name of the used postprocessor specifies the format of the output file, default=IDEAS.
IDEAS 
universal file, see vemide. 
PATRAN 
neutral file, see vempat. 
isvas 
isvas file format, see vemisv. 
ensight 
EnSight file format, see vemens. 
avsucd 
AVS UCD file format, see vemavs. 
print 
formatted print, see vemu01 
gnuplot 
easy readable result file, see vegp97 and vemu13. 
 NK
 Number of solution components, default=1.
 DIM
 Space dimension (DIM=1,2,3), default=3.
 PROCESS_STORAGE
 Total main storage of the calculation per processor in Mbytes, default=20. It is impossible to compute the needed length for PROCESS_STORAGE before the first run. It depends on the given mesh and the functional equation. The needed storage can be controlled by the parameters SOLVER_MSPACK, and SOLVER_PCLASS. STORAGE should be as large as possible, but it is limited by the available storage on the used computer.
 PROCESS_MAXNN
 Maximal number of nodes per processor, default=1000.
 PROCESS_MAXNE
 Maximal number of elements per processor, default=1000.
 MESH_OUTCNT
 If =1, a protocol of the mesh input is printed, default=1.
 MESH_FILEIN
 Name of the file with the mesh data, default=meshin.unv.
 MESH_REDUCE
 Sequence of NK digits 1 and 0 which specifies the approximation orders of the solution components, default=000...0 (for all components the approximation order is equal to the geometrical order, called isoparametrical mesh). If the ith digit is equal to 1, the polynomial order is reduced to order one for component i, in the other case the order of the geometrical mesh is used for the approximation of the solution component i. Components of the solution whose derivatives with respect to space are not involved in the functional should be approximated with a reduced order.
 MESH_TITLE
 Title of the output mesh, default=mesh. It is only used if MESH_POSTP!= MESH_PREP.
 MESH_FILEOUT
 Name of output file for the mesh, default=meshout.unv. It is only used if MESH_POSTP!= MESH_PREP.
 SOLVER_OUTCNT
 Output control of the solver, default=100.
0 
only error messages are printed 
>0 
in addition a protocol is printed and lsolpp prints every SOLVER_OUTCNTth iteration step. 
 SOLVER_ORDER
 Order of the integration formulas for the computation of the element matrices (0<SOLVER_ORDER<19), default=2. SOLVER_ORDER gives the maximal degree of the polynomials which will be integrated exactly. You should select SOLVER_ORDER greater than the square of the order of the used proposal functions.
 SOLVER_MSPACK
 Maximal number of stripes to pack the global matrix, default=100. The packing of the global matrix is divided into several steps (called stripes). Before the packing begins, the needed number of stripes is estimated. If this number is greater than SOLVER_MSPACK, the computation will be stopped. You have to give more storage PROCESS_STORAGE or increase SOLVER_MSPACK. In general a problem needing more than 100 stripes is too large for the given storage, or else the mesh is numbered badly.
 SOLVER_PCLASS
 Packing limit, default=0. The global matrix is stored in packed form. The needed storage can be controlled by SOLVER_PCLASS.
0 
lsolpp will need minimal CPU time. 

The needed storage is large. 
1 
compromise of needed storage and CPU time for lsolpp. 
2 
The storage for the global matrix will be minimal. lsolpp will need much CPU time. 
 SOLVER_MAXIT
 Maximal number of NewtonRaphson steps, default=0. If SOLVER_MAXIT=0, no limit for the number of iterations is set.
 SOLVER_MS
 Method selection in lsolpp, default=10 (Polyalgorithm PRES20 > BICO > ATPRES).
1 
PRES20 
2 
BICO 
3 
BiCGSTAB 
4 
ATPRES 
5 
CGS 
6 
QMRSimulator 
7 
GMERR 
9 
CGAT for nonsymmetric matrices 
10 
Polyalgorithm PRES20 > BICO > ATPRES 
100 
Polyalgorithm PRES20 > BICO > ATPRES (version 2) 
123 
classical CG for symmetric matrices 
 SOLVER_MSPREC
 Normalization method lsolpp, default=11 (symmetrical line normalization).
0 
no normalization 
1 
line sum 
2 
main diagonal elements 
3 
sum of squares of line elements 
4 
Frobenius normalization 
11 
line sum, symmetrical 
12 
main diagonal elements, symmetrical 
13 
sum of squares of line elements, symmetrical. 
14 
symmetrical Frobenius normalization 
 SOLVER_ITMAX
 permitted maximal number of matrixvector multiplications per NewtonRaphson step in lsolpp, default=100 000.
 SOLVER_EPSEST
 Desired accuracy for the solution of the linear systems to compute the error indicator, default=1.D2.
 SOLVER_TOL
 Desired accuracy for the relative error of the solution, e.g. 1.D3. The step size and order will be selected to keep the estimated error lower than TOL.
 SOLVER_ERRSTP
 If =1, the estimation of the discretization error is considered in the stopping criterion of the NewtonRaphson iteration and the step size control, default=0. The iteration ends if the estimated discretization is reached, so that no computing time is wasted to reach a too strict SOLVER_TOL.
 SOLVER_SMLLCR
 If =1, a NewtonRaphson correction which is too small will be accepted, in the other case the solution processes is stopped, default 0. If the problem is very ill posed a small NewtonRaphson correction is not an indicator for a good solution. SOLVER_SMLLCR=1 should only be set, if you are sure that your problem is well posed or you solve a test problem.
 SOLVER_ERREST
 If =1, the error indicator is computed, default=1.
 SOLVER_USESNI
 If =1, the simplified NewtonRaphson method may be used, default=1. The use of the simplified NewtonRaphson method will reduce the CPU time, since the mounting of a new global matrix is saved, but it might be risky in the case of illposed problems.
 SOLVER_SMOOTH
 If =1, lsolpp returns the smoothed solution, default =1. For some applications the use of the nonsmoothed solution can improve the convergence of the NewtonRaphson iteration.
 SOLVER_LMVM
 If =1, the NewtonRaphson iteration is continued even if lsolpp reaches the maximal number of matrixvector multiplications, default=1.
 SOLVER_NORMMA
 If =1, the NewtonRaphson iteration, the step size and the consistency order are controlled by the maximum error over all components, else they are controlled by the error of each individual component, default=0.
 SOLVER_STEADY
 If SOLVER_STEADY=1, a steady problem is assumed and all Tdependencies are removed (t=0, ut=0), default =1
 SOLVER_T0
 Initial time, default =0.
 SOLVER_TEND
 End time. The Integration in Tdirection ends if the current time step is greater than SOLVER_TEND, default =100.
 SOLVER_H
 Initial step size, default =1.D4. It should not be selected too large to avoid failure of the first Tstep.
 SOLVER_HMIN
 Minimal step size in Tdirection, default =1.D8. If the current step size is equal to SOLVER_HMIN, the error is accepted even if it is too large. Setting SOLVER_HMIN to a sufficiently small positive value avoids decrease of the current step size down to zero.
 SOLVER_HMAX
 Maximal step size in Tdirection, default =0. In rare cases, for example when the solution is very smooth and almost constant, but also shows oscillations in short intervals, it may be necessary to choose SOLVER_HMAX according to the problem. If SOLVER_HMAX=0, the maximal step size is set to SOLVER_TENDSOLVER_T0.
 SOLVER_ALLP
 If SOLVER_ALLP=1, the consistency order in the time direction is controlled in the range of 1 to p+1, else in the range of p1 to p+1, where p is the current order, default = 0.
 SOLVER_DT
 Time increment for solution output, default = 1.
 SOLVER_INTERP
 If SOLVER_INTERP=1, the solution is returned at the equidistant time marks SOLVER_T0+ i* SOLVER_DT for i=1,2,... until SOLVER_TEND is reached. In the other cases, the solution is returned at independently selected time marks, but the minimal width is SOLVER_DT and the maximal width is SOLVER_HMAX, default = 0.
 OUTPUT_OUTCNT
 If =1, a protocol of the solution output is printed, default=0.
 OUTPUT_INDEX
 For the output, the components of the solution have to be separated into OUTPUT_NSEL sets so that the selected components in a set can be processed by the postprocessor. Typically the components of a set represent a velocity field or a temperature distribution. OUTPUT_INDEX is a sequence of NK*OUTPUT_NSEL digits 1 and 0, where the digits 1,..., NK mark the components of the first set, the digits NK+1,..., 2*NK the components of the second set and so on. If the d+NK*(j1)th digit is equal to 1, the component d is considered in the jth set, in the other cases it is ignored, default=111.
 OUTPUT_FILE
 Names of the output file for the sets of the selected solution components. The OUTPUT_NSEL names have to be separated by commas. A missing file name for the jth set is set to 'solution.file<j>'.
 OUTPUT_TITLE
 Title of the output file for the sets of the selected solution components. The OUTPUT_NSEL names have to be separated by commas. A missing title for the jth set is set to 'solution.file<j>'.
 OUTPUT_ERRELEM
 If =1, the error indicator is evaluated at the center points of the inner elements, else it is evaluated at the geometrical nodes, default=1. Some pre/postprocessors offer tools to refine the mesh by a given error indicator at the center points.
 OUTPUT_ERRINDEX
 For every component of the solution an indicator for the error distribution is computed, see VECFEM. For the output it is condensed to a scalar value, which is the maximum over selected solution components relative to the maximum norm of the component over the total domain. OUTPUT_ERRINDEX is a sequence of NK digits 1 and 0, where the ith digit, if 1, indicates that the ith component is considered in the condensation, default=1....1 (all components are considered).
 OUTPUT_ERRFILE
 Name of the output file for the condensed error indicator, default=error.out.
 OUTPUT_ERRSCAL
 For output the error indicator is scaled by OUTPUT_ERRSCAL, default = 1. For some postprocessors the error indicator has to be scaled in the order of one to avoid that small values are set to zero by the postprocessor.
EXAMPLES
 See also vemexamples. For the computation of a temperature distribution via the 2dimensional Poisson equation the resource file has the following form, see equation. The program will use 30Mbytes storage. The mesh is read from the PATRAN neutral file test.neutral.
PROCESS_STORAGE = 30
NK = 1
DIM = 2
MESH_PREP = PATRAN
MESH_POSTP = PATRAN
MESH_FILEIN = test.neutral
#
# The mesh has about 10 000 nodes, 2 500 elements
#
PROCESS_MAXNN = 10 000
PROCESS_MAXNE = 2 500
#
# The functional equation is solved with an accuracy of 10^3.
# The solution is written to the data set temp.out. The error
# indicator is written to the default file error.out.
#
SOLVER_TOL = 1.D3
OUTPUT_FILE = temp.out
 The second example is the 3dimensional NavierStokes Equation, see equation. The program will run with 10Mbytes per processor. The mesh is read from the IDEAS universal file channel.unv. The approximation order for the pressure, which is the fourth component of the solution, is reduced to a linear approximation.
PROCESS_STORAGE=10
NK=4
DIM=3
MESH_FILEIN=channel.unv
MESH_REDUCE=0001
#
# The velocity and the pressure are written to the data sets
# velo.unv and pres.unv in the default IDEAS format. The error
# indicator considers only the error in the velocities:
#
OUTPUT_INDEX = 1110 0001
OUTPUT_FILE = velo.unv, pres.unv
OUTPUT_TITLE = velocity, pressure
OUTPUT_ERRINDEX = 1110
VARIABLES
 The shell variables $VECFEM_ROOT and $VECFEM_ALGEBRA are set by the shell script 'vempfade', which is started by vembuild, see vemcompile.
FILES
<workpiece>.resource 
the control parameters, input. 
<workpiece>.equation 
the functional equation, input, see equation. 
<workpiece>.f 
the FORTRAN source code for the problem solution code, output. 
$VECFEM_ROOT/vemtool/*.h 
portions of FORTRAN source code 
/tmp/* 
temporary files 
SEE
 VECFEM, xvem, equation, vemcompile, vemrun, vemhint, vemexamples, idevem, patvem, veid97, veis97, vemavs veme02, vemge2, vemide, vemisv, vempat, vemu02, vepa97, lsolpp
RESTRICTIONS
 1.
 Currently there is only a poor syntax check. If the syntax in <workpiece>.equation is illegal, the algebra program will stop. A syntax error is often produced by the use of a symbol, which is a reserved symbol of the algebra program. In maple all symbols of the form t<i> or s<i>, where i is an integer , will produce chaotic results. If you use illegal data types especially in <workpiece>.resource, you will get errors during the compilation. If you use illegal names for data sets or undefined symbols in the definition of your functional equation, you will get a breakdown during run time. Therefore you should carefully check your syntax especially if you get errors.
 2.
 The generated program processes only meshes of order 2, which is checked by vem099. This avoids problems which could be effected by a fatal selection of the mesh order. If you delete the statement in the FORTRAN code which checks the vem099 return code, you can also use meshes of order 3 or 1.
COPYRIGHTS
 Program by L. Grosz, S. Scheffrahn, 19941996. Copyrights by Universitaet Karlsruhe 19891996. Copyrights by Lutz Grosz 1996. All rights reserved. More details see VECFEM.
 By L.Grosz, Auckland, 31 May, 2000.
