\documentstyle[color,epsfig]{article}
\pagestyle{plain}
\textheight=24cm
\leftmargin=0cm
\textwidth=15cm
\parskip=1em
\parindent=0em
\topmargin=-3cm
\pagecolor{white}

\begin{document}

\title{TOCHNOG programmers manual}
\author{Dennis Roddeman}
\maketitle

\clearpage
\tableofcontents

\clearpage
\section{Implementation of the convection-diffusion equation}

In this section we will show how the convection-diffusion equation is implemented.
We do this for the one-dimensional equation.
See the users manual for the convection-diffusion (heat) equation:

\begin{displaymath}
  \rho C ( \dot{T} + \beta \frac{\partial T}{\partial x} ) =
  k \frac{\partial^2 T}{\partial {x}^2} - a T + f
\end{displaymath}

where we take here for simplicity a prescribed temperature $T$ at $x=0$ and $x=1$.
Multiplication with a weighting function (=test function) $h$
and integration over the volume gives:

\begin{displaymath}
  \int [ \rho C ( \dot{T} + \beta \frac{\partial T}{\partial x} ) h ] dx =
  \int [ k \frac{\partial^2 T}{\partial {x}^2} h - a T h + f h ] dx
\end{displaymath}

where $h$ is $0$ at $x=0$ and $x=1$ but arbitrary otherwise.
Integration by parts of the conductive term, and moving everything to the right
gives for the residue $R$ in the equation:

\begin{displaymath}
  R = \int [ - \rho C ( \dot{T} + \beta \frac{\partial T}{\partial x} ) h 
            - k \frac{\partial T}{\partial x} \frac{\partial h}{\partial x} - a T h + f h ] dx = 0
\end{displaymath}

where the boundary terms resulting from the integration by parts disappear
because $h$ is 0 at $x=0$ and $x=1$.
This form of the equilibrium equation is called the 'weak form'.

The weak form above is still perfectly equal to the heat equation.
Now, however, we start approximating with the finite element method.
The temperature field $T$ is approximated with finite element interpolation
functions $T_j(x)$ where $j$ denotes the node number.
In the standard galerkin approach, the same functions for the 
weighting field is used, so $h$ is approximated with $h_i(x)$.
Remark 1: we use indices $i$ for the weighting function to prevent conflicting
indices of the temperature and weighting functions.
Remark 2:$h$ can now be called a virtual temperature field, since it consists
of the same set of functions as the temperature field itself.
So:

\begin{displaymath}
  T = T(x_j) T_j(x)
\end{displaymath}

and:

\begin{displaymath}
  h =  h(x_i) h_i(x)
\end{displaymath}

where $x_j$ is the position of node $j$, and summation convention is used.
For a two-noded linear element this would be:

\begin{displaymath}
  T = T(0) (1-x) + T(1) x
\end{displaymath}

and:

\begin{displaymath}
  h = h(0) (1-x) + h(1) x
\end{displaymath}

The weighting functions are substituted in the weak form of the equilibrium equation:

\begin{displaymath}
  R = \int [ - \rho C ( \dot{T} + \beta \frac{\partial T}{\partial x} ) h(x_i) h_i(x) -
            h(x_i) k \frac{\partial T}{\partial x} \frac{\partial h_i(x)}{\partial x} - 
            a T h(x_i) h_i(x) + f h(x_i) h_i(x) ] dx = 0
\end{displaymath}

Now demanding that this is true for arbitrary nodal weighting function values $h(x_i)$ gives
for each $i$:

\begin{displaymath}
  R = \int [ - \rho C ( \dot{T} + \beta \frac{\partial T}{\partial x} ) h_i(x) - 
            k \frac{\partial T}{\partial x} \frac{\partial h_i(x)}{\partial x} - 
            a T h_i(x) + f h_i(x) ] dx = 0
\end{displaymath}

The time derivative $\dot{T}$ will be approximated with
the Euler backward scheme $ \frac{T(t+dt)-T(t)}{dt} $.
Integrals are approximated by numerically integrating over a set of integration points. 
The temperature $T$ in the last expression is understood to be interpolated
by the finite element interpolation functions, and so depends on the
nodal temperatures $T(x_j)$.
Thus the last expression gives a set of equations for the nodal temperatures $T(x_j)$.

We now will discuss where the seperate terms in this expression are implemented
in the finite element program.
First we link terms from the expression for $R$ with the program source: \\

\begin{center}
\begin{tabular}{ll}
  \underline{mathematical term} & \underline{\textcolor{red}{program}} \\
  $R$ & \textcolor{red}{element\_rhside} \\
  $\rho$ & \textcolor{red}{dens} \\
  $C$ & \textcolor{red}{condif\_capacity} \\
  $\beta$ & \textcolor{red}{condif\_flow} \\
  $k$ & \textcolor{red}{condif\_conductivity} \\
  $a$ & \textcolor{red}{condif\_absorption} \\
  $f$ & \textcolor{red}{element\_volume\_force} \\
  $T(t+dt)$ &  \textcolor{red}{new\_dof} \\
  $T(t)$ & \textcolor{red}{old\_dof} \\
  $dt$ & \textcolor{red}{dtime} \\
  $i$ & \textcolor{red}{inol} \\
  $h_i(x)$ & \textcolor{red}{h[inol]} \\
  $ \frac{\partial h_i(x)}{\partial x}$ & \textcolor{red}{new\_d} \\
\end{tabular}
\end{center}

Different parts of $R$ are implemented in different routines.
First, it will be collected in the variable \textcolor{red}{element\_rhside}.
Later, \textcolor{red}{element\_rhside} will be used to fill \textcolor{red}{node\_rhside}
which contains the residue $R$ for the nodes.

\begin{itemize}
\item The term $ - \rho C \dot{T} h_i(x) $ is implemented in \textcolor{red}{general.cc}.
      The time derivative $ \dot{T} $ is evaluated lumped.
      The implementation of this term is marked by 
      the comment \textcolor{red}{// inertia (lumped)}.
\item The term $ - \rho C  \beta \frac{\partial T}{\partial x} h_i(x) $ is 
      implemented in \textcolor{red}{general.cc}.
      The implementation of this term is marked 
      by the comment \textcolor{red}{// convection with respect to mesh}.
\item The term $ - k \frac{\partial T}{\partial x} \frac{\partial h_i(x)}{\partial x} $ is implemented
      in \textcolor{red}{general.cc}.
      The implementation of this term is marked 
      by the comment \textcolor{red}{// diffusive terms (with partial integration)}.
\item The term $- a T h_i(x)$ is implemented in \textcolor{red}{condif.cc}.
      The implementation of this term is marked 
      by the comment \textcolor{red}{// absorption}.
\item The term $ + f h_i(x) $ is implemented in \textcolor{red}{elem.cc}.
      The implementation of this term is marked 
      by the comment \textcolor{red}{// element force}.
\end{itemize}

\clearpage
\section{Variables}

Typically use of variables is  as follows:

\begin{center}
\begin{tabular}{ll}
 \underline{\textcolor{red}{program variable}} & \underline{meaning} \\
 \textcolor{red}{element} & global element number. \\
 \textcolor{red}{max\_element} & highest global element number. \\
 \textcolor{red}{inod} & global node number. \\
 \textcolor{red}{max\_node} & highest global node number. \\
 \textcolor{red}{inol} & element node number. \\
 \textcolor{red}{nnol} & the number of element nodes. \\
 \textcolor{red}{ipuknwn} & primary unknown number. \\
 \textcolor{red}{npuknwn} & the number of primary unknowns. \\
 \textcolor{red}{iuknwn} & unknown number. \\
 \textcolor{red}{nuknwn} & the number of unknowns. \\
\end{tabular}
\end{center}

\clearpage
\section{Routines}

The most important program structure is shown below:

\textcolor{red}{tn} (main routine) \\
  \textcolor{white}{mm} \textcolor{red}{input} (read input) \\
  \textcolor{white}{mmmm} \textcolor{red}{db\_initialize} (initialize the database) \\
  \textcolor{white}{mm} \textcolor{red}{top} (time step loop) \\
  \textcolor{white}{mmmm} \textcolor{red}{elem} (element loop, integration point loop) \\
  \textcolor{white}{mmmmmm} \textcolor{red}{general} (generic element part) \\
  \textcolor{white}{mmmmmm} \textcolor{red}{condif} (convection\_diffusion equation) \\
  \textcolor{white}{mmmmmm} \textcolor{red}{materi} (materi equation) \\
  \textcolor{white}{mmmmmmmm} \textcolor{red}{stress} (stress evaluation ) \\
  \textcolor{white}{mmmmmmmmmm} \textcolor{red}{plasti} (plasticity evaluation) \\
  \textcolor{white}{mmmmmm} \textcolor{red}{wave} (wave equation)\\
  \textcolor{white}{mmmm} \textcolor{red}{solve} (solve equations) \\
  \textcolor{white}{mmmm} \textcolor{red}{refine\_globally} (h- and p-refinement) \\
  \textcolor{white}{mmmm} \textcolor{red}{refine\_locally} (local h-refinement) \\
  \textcolor{white}{mmmm} \textcolor{red}{print} (print outpout) \\
  \textcolor{white}{mm} \textcolor{red}{tn\_exit} (exit tochnog) \\

Below, all files are listed:

\begin{itemize}

\item \textcolor{red}{adjust.cc}

  Evaluate {\bf control\_mesh\_adjust\_geometry}.

\item \textcolor{red}{area.cc}

  Evaluate area integrals like {\bf condif\_radiation}, 
  {\bf condif\_convection}, and {\bf force\_element\_edge}.

\item \textcolor{red}{bounda.cc}

  Evaluate boundary conditions like {\bf bounda\_unknown}, 
  {\bf bounda\_force}, {\bf bounda\_time} and {\bf bounda\_sine}.

\item \textcolor{red}{calcul.cc}

  Evaluate {\bf post\_calcul}.

\item \textcolor{red}{cblas.c}

  cblas routines from netlib.

\item \textcolor{red}{check.cc}

  Check validity of data in input file.

\item \textcolor{red}{clapack.c}

  clapack routines from netlib.

\item \textcolor{red}{condif.cc}

  Evaluate for type {\bf -condif} whatever is not evaluated 
  in \textcolor{red}{general.cc}.

\item \textcolor{red}{contact.cc}

  Evaluate contact data like {\bf contact\_geometry}, etc.

\item \textcolor{red}{create.cc}

  Create an element or a node.

\item \textcolor{red}{damage.cc}

  Evaluate damage like {\bf materi\_damage\_mazars}.

\item \textcolor{red}{data.cc}

  Evaluate {\bf control\_data\_delete} and {\bf control\_data\_put}.

\item \textcolor{red}{database.cc}

  Specification of properties of items in database
  and database routines.

\item \textcolor{red}{delete.cc}

  Delete an element or a node or the elements and nodes in
  a geometry.

\item \textcolor{red}{dof.cc}

  Routine for Degrees Of Freedom.

\item \textcolor{red}{elasti.cc}

  Determine material stiffness matrix from
  {\bf materi\_elasti\_young} and {\bf materi\_elasti\_poisson}.

\item \textcolor{red}{elem.cc}

  Element loop. Called from top.cc.

\item \textcolor{red}{equal.cc}

  Evaluate {\bf dof\_equal}.

\item \textcolor{red}{error.cc}

  Evaluate {\bf post\_error\_item}.

\item \textcolor{red}{failure.cc}

  Evaluate {\bf materi\_strain\_plasti\_failure}, 
  {\bf materi\_strain\_total\_failure} and {\bf materi\_damage\_failure}.

\item \textcolor{red}{filter.cc}

  Evaluate {\bf print\_filter}.

\item \textcolor{red}{force.cc}

  Evaluate {\bf force\_element\_volume\_factor} and other force info.

\item \textcolor{red}{general.cc}

  Generic part of different types ({\bf condif}, {\bf wave}, {\bf materi}, etc).

\item \textcolor{red}{geometry.cc}

  Evaluate geometry data items (like {\bf geometry\_point}, etc.).

\item \textcolor{red}{groundfl.cc}

  Evaluate for type {\bf -groundflow} whatever is not evaluated 
  in \textcolor{red}{general.cc}.

\item \textcolor{red}{group.cc}

  Evaluate element group things like {\bf area\_element\_group}
  and {\bf dependency\_item}.

\item \textcolor{red}{hyperela.cc}

  Hyperelastic laws {\bf materi\_hyper\_besseling} and 
  {\bf materi\_hyper\_mooney\_rivlin}.

\item \textcolor{red}{initia.cc}

  Initialise global variables.

\item \textcolor{red}{input.cc}

  Read the input file.

\item \textcolor{red}{integra.cc}

  Integration rules (gauss and lobatto).

\item \textcolor{red}{intersec.cc}

  Calculate intersections (line with line, line with point, etc.).

\item \textcolor{red}{inverse.cc}

  Evaluate inverse data like {\bf inverse\_parameter\_set}, etc.

\item \textcolor{red}{locate.cc}

  Evaluate {\bf node\_locate}, etc.

\item \textcolor{red}{macro.cc}

  Evaluate {\bf control\_mesh\_macro}.

\item \textcolor{red}{map.cc}

  Map element and nodal data from one mesh to another mesh.

\item \textcolor{red}{materi.cc}

  Evaluate for type {\bf -materi} whatever is not evaluated in general.cc.

\item \textcolor{red}{math.cc}

  Generic mathematical routines, like matric-vector operations, etc.

\item \textcolor{red}{membrane.cc}

  Evaluate {\bf materi\_membrane}.

\item \textcolor{red}{merge.cc}

  Evaluate {\bf control\_mesh\_merge}.

\item \textcolor{red}{mesh.cc}

  Mesh operation. Update element and node data if a mesh has changed.
  Add one mesh to another.

\item \textcolor{red}{miscel.cc}

  Miscelaneous stuff.

\item \textcolor{red}{new\_mesh.cc}

  Evaluate {\bf control\_mesh\_new\_mesh\_region}.

\item \textcolor{red}{node.cc}

  Determine nodes in the direct neighbourhoud of a node.

\item \textcolor{red}{plasti.cc}

  Materi stress plasticity evaluation.

\item \textcolor{red}{point\_el.cc}

  Determine of a point in which element it is located
  and what the corresponding weightingfactors of the
  element's nodes are.

\item \textcolor{red}{polynom.cc}

  Determine an element interpolation functions, its derivatives, etc.

\item \textcolor{red}{post.cc}

  Evaluate {\bf post\_point}, etc.

\item \textcolor{red}{pri.cc}

  Print routines for test printing.

\item \textcolor{red}{print.cc}

  Evaluate {\bf control\_print}.

\item \textcolor{red}{print\_da.cc}

  Evaluate {\bf control\_print\_data\_versus\_data}.

\item \textcolor{red}{print\_gm.cc}

  Evaluate {\bf control\_print\_gmv}.

\item \textcolor{red}{print\_hi.cc}

  Evaluate {\bf control\_print\_history}.

\item \textcolor{red}{print\_ma.cc}

  Evaluate {\bf control\_print\_matlab}.

\item \textcolor{red}{print\_pl.cc}

  Evaluate {\bf control\_print\_plotmtv}.

\item \textcolor{red}{print\_te.cc}

  Evaluate {\bf control\_print\_tecplot}.

\item \textcolor{red}{project.cc}

  Projections (point on line, etc.).

\item \textcolor{red}{range.cc}

  Evaluate a range {\bf -ra ... -ra}.

\item \textcolor{red}{refine\_g.cc}

  Evaluate {\bf control\_mesh\_refine\_globally}.

\item \textcolor{red}{refine\_l.cc}

  Evaluate {\bf control\_mesh\_refine\_locally}.

\item \textcolor{red}{remesh.cc}

  Evaluate {\bf control\_mesh\_remesh}.

\item \textcolor{red}{renumber.cc}

  Evaluate {\bf control\_mesh\_renumber}.

\item \textcolor{red}{repeat.cc}

  Evaluate {\bf control\_repeat}.

\item \textcolor{red}{restart.cc}

  Evaluate {\bf control\_restart}.

\item \textcolor{red}{slide.cc}

  Evaluate {\bf slide\_geometry}, etc.

\item \textcolor{red}{solve.cc}

  Matrix solver and also eigenvalue calculations.

\item \textcolor{red}{split.cc}

  Evaluate {\bf control\_mesh\_split}.

\item stress.cc

  Materi stress evaluation. Called from \textcolor{red}{materi.cc}.

\item \textcolor{red}{sysother.cc}

  Routine if not \textcolor{red}{sysposix.cc}, \textcolor{red}{syssgi.cc}.

\item \textcolor{red}{sysposix.cc}

  Specially for posix systems.

\item \textcolor{red}{syssgi.cc}

  Specially for sgi systems.

\item \textcolor{red}{tendon.cc}

  Evaluate {\bf tendon}.

\item \textcolor{red}{tn.cc}

  Highest level routine.

\item \textcolor{red}{top.cc}

  Main loops like inverse iterations, time integration, 
  equilibrium iterations, etc.

\item \textcolor{red}{tyings.cc}

  Setup and apply tyings.

\item \textcolor{red}{umat.c}

  umat routine to enable usage of abaqus umat.f routines.

\item \textcolor{red}{user.cc}

  User supplied routines.

\item \textcolor{red}{viscoela.cc}

  Evaluate {\bf materi\_maxwell\_chain}.

\item \textcolor{red}{viscosit.cc}

  Evaluate {\bf materi\_viscosity}.

\item \textcolor{red}{volume.cc}

  Evaluate {\bf volume\_factor} and {\bf volume\_element\_factor}.

\item \textcolor{red}{wave.cc}

  Evaluate for type {\bf -wave} whatever is not evaluated 
  in \textcolor{red}{general.cc}.

\end{itemize}

\clearpage
\section{Database}

The file \textcolor{red}{database.cc} contains:

\begin{itemize}
  \item Arrays with actual data and information arrays.
  \item Acces routines.
\end{itemize}

The actual data and information about it is stored in a number of arrays:
\begin{itemize}
  \item \textcolor{red}{dbl\_data}
    This array contains pointers to the actual double data.
    It has so for all possible data (\textcolor{red}{MDAT}), and for all possible
    versions of the data (\textcolor{red}{MVERSION}).
    (Some data, like element data and nodal data, can exist in more than one
     version; that is, it can exist on more than one mesh).
  \item \textcolor{red}{int\_data}
    The same as \textcolor{red}{dbl\_data} but now for integers however.
  \item \textcolor{red}{max\_index}
    The maximum index allocated for the data item.
  \item \textcolor{red}{no\_index}
    Set to 1 if the data item doesn't have an index, 
    like \textcolor{red}{NUMBER\_OF\_PROCESSORS}.
  \item \textcolor{red}{type}
    \textcolor{red}{INTEGER} for integer data, 
    and \textcolor{red}{DOUBLE} for double data.
  \item \textcolor{red}{name}
    The name, e.g. {\bf element} for data item \textcolor{red}{ELEMENT}.
  \item \textcolor{red}{external}
    Set to 1 if it is user data, set to 0 if it is internally for tn only.
  \item \textcolor{red}{data\_length}
    Set to the length of the data item (or the maximum length in
    the data item doesn't have a fixed length).
  \item \textcolor{red}{fixed\_length}
    Set to 1 if the length of the data item is fixed, 
    set 0 0 if the length of the data item is not a priori fixed.
  \item \textcolor{red}{data\_class}
    The class a data item belongs to. 
    E.g. \textcolor{red}{ELEMENT\_GROUP} belongs to the class \textcolor{red}{ELEMENT}. 
    This allows for operations on a class,
    like deleting an element and all its properties.
  \item \textcolor{red}{print\_only}
    Set to 1 if the data item is meant for printing after the calculation only,
    and thus is not allowed to be input in the data file.
  \item \textcolor{red}{version\_all}
    Set to 1 if all versions (meshes) of a data item can exist.
    E.g. of \textcolor{red}{ELEMENT} all versions can exist, 
    but of \textcolor{red}{NUMBER\_OF\_PROCESSORS} only one version can exist.
\end{itemize}

There are a number of routines to acces the data.
The most important routines are listed below:
\begin{itemize}
  \item \textcolor{red}{db(idat,index,*ival,*dval,\&length,version,task)}
     This is the main routine to acces data on the database.
     The data can either be read or written with this routine.
     \begin{itemize}
       \item The data item accessed is \textcolor{red}{idat}, 
         e.g. \textcolor{red}{idat} is \textcolor{red}{ELEMENT}, 
         or \textcolor{red}{idat} is  \textcolor{red}{NODE}, etc.
       \item The index, for the data item, accessed is \textcolor{red}{index} 
       \item Integer data is accessed via the \textcolor{red}{ival} array.
       \item Double data is accessed via the \textcolor{red}{dval} array.
       \item The length of the data item is contained in \textcolor{red}{length}.
             If the data is read, the length is returned.
             If the data is written, the length should be set.
       \item The version of the data should be set in \textcolor{red}{version}.
             This is either \textcolor{red}{VERSION\_NORMAL}, or \textcolor{red}{VERSION\_NEW}, etc.
             See the discussion of versions in a seperate section below.
       \item The task to be performed is et in \textcolor{red}{task}.
             If the data is written then set \textcolor{red}{task} to \textcolor{red}{PUT}.
             If the data is read then set \textcolor{red}{taks} to \textcolor{red}{GET}.
             Some other \textcolor{red}{task} options exist.
     \end{itemize}
  \item \ldots
\end{itemize}

\clearpage
\section{Versions}

Of some data more than one version can exist in the database.
This gives the possibility to keep more values 
for the data items in the database.
This is used to store e.g. nodal unknowns at the old time point t,
while the new nodal unknowns are being calculated in the current
time step.
Moreover, it comes handy at mesh refinements, where data for the old coarse mesh
and the refined new mesh are avaiable at the same time, etc.
Some of the allowed versions are listed below:

\begin{center}
\begin{tabular}{ll}
 \underline{version} & \underline{purpose} \\
 \textcolor{red}{VERSION\_NORMAL} & Normal working version. Keeps unknowns at old time point t. \\
 \textcolor{red}{VERSION\_NEW}  & New mesh. Keeps unknowns at time t+dt. \\
 \textcolor{red}{VERSION\_START} & Keeps the mesh at the start of the calculation; for restarts. \\
 \textcolor{red}{VERSION\_TMP} & Temporarily working version (scratch version). \\
 \textcolor{red}{VERSION\_PRINT} & Temporarily version for printing (some plotters require sequential numbering). \\
 \textcolor{red}{VERSION\_MACRO} & Temporarily version for control\_macro option. \\
 \textcolor{red}{\ldots} & \ldots \\
\end{tabular}
\end{center}

\clearpage
\section{Debugging}

Activate debug printing by setting the environment symbol \textcolor{red}{TOCHNOG\_DEBUG} to {\bf yes}.

Printing can be limited by setting the following environment symbols:
\begin{center}
\begin{tabular}{ll}
 \underline{environment symbol} & \underline{purpose} \\
 \textcolor{red}{TOCHNOG\_ELEMENT} {\it element\_number} & Printing for specific element only. \\
 \textcolor{red}{TOCHNOG\_ICONTROL} {\it control\_number} & Printing for specific control index only. \\
 \textcolor{red}{TOCHNOG\_ITERATION} {\it iteration\_number} & Printing for specific iteration only. \\
 \textcolor{red}{TOCHNOG\_NODE} {\it node\_number} & Printing for specific node only. \\
 \textcolor{red}{TOCHNOG\_ROUTINE} {\it routine\_name} & Printing for specific routine only. \\
\end{tabular}
\end{center}

You also can set the environment variable \textcolor{red}{TOCHNOG\_REPORT\_ROUTINE}.
Then tn reports the routines it passes.

After a calculation, the entire database can be printed by
using {\bf control\_print\_database} {\it index} {\bf -everything}.
This prints, besides the normal user variables, also internal variables.

\end{document}
