# 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 non-linear 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 lower-case 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=I-DEAS. 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:
I-DEAS - input file is an I-DEAS universal file
  The following table shows the allowed element types, see idevem:

domain | I-DEAS 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 x-displacement in the i-th restraint set. The prevalue parameter in the definition of the Dirichlet condition of component d is set to the value of the x-displacement.
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 x-displacements in the constraint set with set-id i. The prevalue parameter in the definition of the Dirichlet condition of component d is set to the value of the x-displacement.
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 | 1--3--2
area | 2 | 3 | 6 |
    3
    | \
    6  5
    |    \
    1--4--2
| 2 | 4 | 8 |
    4--7--3
    |     |
    8     6
    |     |
    1--5--2
volume | 3 | 6 | 15 |
           6
         / : \
       15  :  14
      /    :    \
     4-----13------5
     |      :      |
     |     12      |
     |      :      |
    10      3      11
     |    /   \    |
     |  9       8  |
     | /          \|
     1------7------2
| 3 | 4 | 10 |
    4
    |\ \
    | \  10
    |  \    \
    |   9      3
    |    \   /  |
    8      X    6
    |     / \   |
    |   7    \  |
    | /        \
    1----5------2
| 3 | 8 | 20 |
         8-----19------7
        / :            /:
      20  :          18 :
      /   :         /   :
     5-------17-----6    :
     |     :        |    :
     |    16        |   15
    13     :       14    :
     |     4-----11-|----3
     |    /         |   /
     |  12          | 10
     | /            |/
     1-------9------2

  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=I-DEAS.

I-DEAS | universal file, see vemide.
PATRAN | neutral file, see vempat.
isvas | isvas file format, see vemisv.
ensight | EnSight file format, see vemens.
avs-ucd | 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 i-th 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_OUTCNT-th 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 Newton-Raphson 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 | Bi-CGSTAB
4 | ATPRES
5 | CGS
6 | QMR-Simulator
7 | GMERR
9 | CG-AT for non-symmetric 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 matrix-vector multiplications per Newton-Raphson step in lsolpp, default=100 000.
SOLVER_EPSEST
  Desired accuracy for the solution of the linear systems to compute the error indicator, default=1.D-2.
SOLVER_TOL
  Desired accuracy for the relative error of the solution, e.g. 1.D-3. 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 Newton-Raphson 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 Newton-Raphson 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 Newton-Raphson 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 Newton-Raphson method may be used, default=1. The use of the simplified Newton-Raphson 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 ill-posed problems.
SOLVER_SMOOTH
  If =1, lsolpp returns the smoothed solution, default =1. For some applications the use of the non-smoothed solution can improve the convergence of the Newton-Raphson iteration.
SOLVER_LMVM
  If =1, the Newton-Raphson iteration is continued even if lsolpp reaches the maximal number of matrix-vector multiplications, default=1.
SOLVER_NORMMA
  If =1, the Newton-Raphson 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 T-dependencies are removed (t=0, ut=0), default =1
SOLVER_T0
  Initial time, default =0.
SOLVER_TEND
  End time. The Integration in T-direction ends if the current time step is greater than SOLVER_TEND, default =100.
SOLVER_H
  Initial step size, default =1.D-4. It should not be selected too large to avoid failure of the first T-step.
SOLVER_HMIN
  Minimal step size in T-direction, default =1.D-8. 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 T-direction, 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_TEND-SOLVER_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 p-1 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*(j-1)-th digit is equal to 1, the component d is considered in the j-th 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 j-th 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 j-th 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 i-th digit, if 1, indicates that the i-th 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 2-dimensional 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.D-3
         OUTPUT_FILE = temp.out

  The second example is the 3-dimensional Navier-Stokes Equation, see equation. The program will run with 10Mbytes per processor. The mesh is read from the I-DEAS 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 I-DEAS 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, 1994-1996. Copyrights by Universitaet Karlsruhe 1989-1996. Copyrights by Lutz Grosz 1996. All rights reserved. More details see VECFEM.

  By L.Grosz, Auckland, 31 May, 2000.