generalities.tex

FreeFEM is an implementation of the GFEM language dedicated to the finite element method. It provid

\textbf{How does it works}
The interpreter evaluates the expression after the ":"
for each triangle and for each 3 vertices; if there
is an instruction prior the ":" it is also evaluated
similarly.  Each evaluation is done with one
of the unknown and one of the test functions being
1 at one vertices and zero at the 2 others.  This
will give an element of the contribution of the triangle
to the linear system of the problem.  The right
hand side is constructed by having all unknowns equal
to zero and one test function equal to one at one
vertex.  whenever integrals appear they are computed
on the current triangle only.

\textbf{Note} that \verb+varsolve+ takes longer than \texttt{solve}
because derivatives like \verb+dx(u)+  are evaluated 9 times
instead of once.


\section{Results}
%%  node-name,  next,  previous,  up


%% plot::                        
%% Saveall()::                   


%% node  plot, Saveall(), Results, Results
\subsection{plot, savemesh, save, load, loadmesh}
%%  node-name,  next,  previous,  up

Within a program the keyword \verb+plot(u)+ will display \verb+u+ .

Instruction \texttt{save('filename',u)} will save the data array \verb+u+  on
disk. If \verb+u+ is a scalar variable then the (single) value of \verb+u+  is
appended to the file (this is useful for time dependent problems or any
problem with iteration loop.).

Instruction \texttt{savemesh('filename')}\index{savemesh@\texttt{savemesh}}
will save the triangulation on disk.

Similarly for reading data with \texttt{load('filename',u)}  and
\texttt{loadmesh('filename')}\index{loadmesh@\texttt{loadmesh}}.

The file must be in the default directory, else it won't be found. The
file format is best seen by opening them with a text editor. For a data
array \verb+f+  it is:
\begin{Verbatim}
ns
f[0]
....
f[ns-1]
\end{Verbatim}
(\verb+ns+  is the number of vertices)

If \verb+f+ is a constant, its single value is \emph{appended}  to the end of the file;
this is useful for time dependent problems or any problem with iteration
loop.

If \verb+precise+  is set still the function stored by save
is interpolated on the vertices as the $P^1$ continuous function given by mass lumping (see above).

For triangulations the file format is (\verb+nt+ = number of triangles):
\index{Mesh formats!\texttt{gfem}}
\begin{Verbatim}
ns nt
q[0].x q[0].y ib[i] 
...
q[n-1].x q[n-1].y ib[n-1]
me[0][0] me[0][1]  me[0][2] ngt[0]
...
me[n-1][0] me[n-1][1]  me[n-1][2] ngt[n-1]
\end{Verbatim}


\paragraph{\textbf{Remark:}}

\textbf{Gfem} uses the Fortran standard for \verb+me[][]+  and
numbers the vertices starting from number 1 instead of 0  as in the
C-standard. Thus in C-programs one must use \verb+me[][]-1+ .


\paragraph{\textbf{Remark:}}

Other formats are also recognized by freefem via their file name extensions
for our own internal use we have defined \verb+.amdba+  and \verb+.am_fmt+.
You can do the same if your format is not ours.

\index{Mesh formats!\texttt{ambda}}
\index{Mesh formats!\verb+am_fmt+}
\begin{Verbatim}
        loadmesh('mesh.amdba'); /* amdba format (Dassault aviation) */
        loadmesh('mesh.am_fmt'); /* am_fmt format of MODULEF */
\end{Verbatim}


\paragraph{\textbf{Remark:}}

There is an optional arguments for the functions \texttt{load}, \texttt{save},
\texttt{loadmesh}\index{loadmesh@\texttt{loadmesh}},
\texttt{savemesh}\index{savemesh@\texttt{savemesh}}. This is the 2nd or 3rd
argument of these functions. Here are the prototypes: 

\begin{Verbatim}
save(<filename>, <function name> 
    [,<variable counter: integer or converted to integer>])
load(<filename>, <function name> 
    [,<variable counter: integer or converted to integer>])
savemesh(<filename>[,<variable counter: 
                      integer or converted to integer>])
loadmesh(<filename>[,<variable counter: 
                      integer or converted to integer>])
\end{Verbatim}


As an example see \texttt{nsstepad.pde} which use this feature to save the
mesh and the solution at each adaptation of the mesh. This special feature
allows you to save or load a generic filename with a counter, the final
filename is built like this \texttt{'<generic filename>-<counter>'}.
%% node  Saveall(),  , plot, Results
\subsection{Saveall()}
%%  node-name,  next,  previous,  up

The purpose is to solve all the data for a PDE or a 2-system with
only one instruction.  It is meant for those who want to write their 
own solvers.

The syntax is:
\begin{Verbatim}
saveall('file_name', var_name1,...)
\end{Verbatim}
The syntax is exactly the same as that of \verb+solve(,)+ \index{solve@\texttt{solve}}  except that the
first parameter is the file name. The other parameters are used only 
to indicate to the interpreter which is/are the unknown function.  

The file format for the scalar equation (\texttt{laplace} is decomposed on
\texttt{nuxx, nuyy})
\begin{Verbatim}
u=p  if Dirichlet
c u+dnu(u)=g if Neumann
b u-dx(nuxx dx(u))-dx(nuxy dy(u))-dy(nuyx dx))-dy(nuyy dy(u))
 + a1 dx(u) + a2 dy(u) =f
\end{Verbatim}
is that each line has all the values for \texttt{x,y}  being a vertex:
\texttt{f, g, p, b, c, a1, a2, nuxx, nuxy, nuyx, nuyy}.

The actual routine is in C++
\begin{Verbatim}
int saveparam(fcts *param, triangulation* t, char *filename, int N)
{ 
  int k, ns = t->np;
  ofstream file(filename);
  file<<ns<<"   "<<N<<endl;
  for(k=0; k<ns; k++) 
  {    
                file << (param)->f[k]<<" " ; file<<"            ";
                file << (param)->g[k]<<" " ; file<<"            ";
                file << (param)->p[k]<<" " ; file<<"            ";
                file << (param)->b[k]<<" " ; file<<"            ";
                file << (param)->c[k]<<" " ; file<<"            ";
                file << (param)->a1[k]<<" " ; file<<"           ";
                file << (param)->a2[k]<<" " ; file<<"           ";
                file << (param)->nuxx[k]<<" " ; file<<"         ";
                file << (param)->nuxy[k]<<" " ; file<<"         ";
                file << (param)->nuyx[k]<<" " ; file<<"         ";
                file << (param)->nuyy[k]<<" " ; file<<"         ";
    file << endl;
  }
}
\end{Verbatim}
The same function is used for complex coefficients, by overloading the
operator <<:
\begin{Verbatim}
friend ostream& operator<<(ostream& os, const complex& a)
 {
   os<<a.re<<" " << a.im<<"             ";  
   return os;   
 }
\end{Verbatim}
For 2-systems also the same is used with
\begin{Verbatim}
ostream& operator<<(ostream& os, cvect& a)
  {
    for(int i=0; i<N;i++) 
      os<<a[i]<<"  "; 
    return os;   
  }
ostream& operator<<(ostream& os, cmat& a)
  {
    for(int i=0; i<N;i++) 
     for(int j=0; j<N;j++) 
       os<<a(i,j)<<"  ";  
    return os;   
  }
\end{Verbatim}         
where \verb+N=2+ .           

A Dirichlet condition is applied whenever p[k](?).  ( Dirichlet
conditions with value \verb+0+ are changed to value \verb+1e-10+ )


\section{Other features}

\textbf{Gfem} supports other interesting features:

\subsection{Iter}

\index{iter@\texttt{iter}}
The syntax is: 
\begin{Verbatim}
iter(j){....}
\end{Verbatim}
where j refers to the number of loops; j can be the result of an expression
(as in \texttt{iter(i*k)}).

Imbedded loops are not allowed. You can use \verb+iter+  with the adaptation
features of \textbf{Gfem}.


%% node  Complex numbers, Scal(), Iter, Other features
\subsection{Complex numbers}
%%  node-name,  next,  previous,  up

\index{complex@\texttt{complex}}
\textbf{Gfem} can handle complex coefficients with  4 dedicated keywords:
\begin{itemize}
\item
\verb+complex+ : to tell Gfem that complex number will be used.
When it is used it must be located at the beginning of the program 
before any  function declarations, otherwise the results will be incorrect.
It can appear more than once in the program but only the first occurrence
counts.

\item \texttt{I}: for \texttt{sqrt(-1)} .

\item \texttt{Re} : for the real part.

\item \texttt{Im} : for the imaginary part.
\end{itemize} 

There is purposely no conjug function but \texttt{barz=Re(z)-I*Im(z)}  will
do.

By default all graphics display the real part. To display the imaginary
part do \texttt{plot(Im(f))}.
 
The functions implemented for complex numbers are:
\begin{itemize}
\item $cos$
\item $sin$
\item $z^x$ where $z$ is complex and $x$ is a float
\end{itemize}

The linear systems for the PDE are solved by a Gauss complex LU 
factorization.

\textbf{WARNING}: failure to declare \verb+complex+  in the program implies all
computation will be done in real, even if \verb+I+  is used. 

%% node  Scal(), Wait, Complex numbers, Other features
\subsection{Scal()}
%%  node-name,  next,  previous,  up

\index{scal@\texttt{scal}}
The instruction \verb+a:=scal(f,g);+  does

  $$ a = \int_\Omega f(x,y) \overline{g}(x,y) dxdy  $$
where $\Omega$ is the triangulated domain.

%% node  Wait, One Dimensional Plots, Scal(), Other features
\subsection{Wait, nowait, changewait}
%%  node-name,  next,  previous,  up

Whenever there is a \verb+plot+ command, \textbf{Gfem}  stops to let the user see
the result. By using \verb+nowait+  no stop will be made; 
\begin{itemize}
\item 
\texttt{wait}  turns back the stop option on.
\item
\texttt{changewait} toggles the option from on to off or off to on.
\end{itemize}

\textbf{Remark under X11}: If you click the right button in the window, the
next time the solver will give the hand to the plotter the program will
stop.

%% node  One Dimensional Plots, Precise, Wait, Other features
\subsection{One Dimensional Plots}
%%  node-name,  next,  previous,  up

This function is \textbf{only available} under integrated environments.

The last function defined by the keyword \verb+plot+  is displayed.  It can
be visualized in several fashion, one of which being  a \textbf{one dimensional
plot} along any segment defined by the mouse. Selection of this menu
brings causes  Gfem to waits for the user input which should be the line
segment on which the function is to be displayed.  Thus one should  \textbf{
press the mouse at the beginning point then drag the mouse and release
the button at the final point} 

It is safe to  click in the window after to  check that the function
display is correct. What is seen is a 

$$t \to f(x(t),y(t))$$

Plot where $[x(t),y(t)]_t$ is the segment drawn by the user and \verb+f+  is
the last function displayed in the plot window.  

The abscissa is the distance with the beginning point.

%% node   Precise, Exec(), One Dimensional Plots, Other features
\subsection{Precise}
%%  node-name,  next,  previous,  up

\index{precise@\texttt{precise}}
This keyword warns \textbf{Gfem} that precise quadrature formula must be
used. Hence array-functions are discretized as piecewise linear
\textbf{discontinuous} functions on the triangulation.  Then all integrals are
computed with 3 inner Gauss points slightly inside each triangle.

This option consumes more memory (3nt instead of ns per functions,
i.e. 9 times more approximately,  but still it is nothing compared with
the memory that a matrix of the linear system of a PDE requires) because
each array-function is stored by 3 values on each triangles.

It is a good idea to use it in conjunction with \verb+convect+
\index{convect@\texttt{convect}} and/or discontinuous nonlinear terms.

%% node  Exec(),  , Precise, Other features
\subsection{Exec(), user(), how to link an external function to Gfem}
%%  node-name,  next,  previous,  up

\index{exec@\texttt{exec}}
\index{user@\texttt{user}}

\verb+exec('prog_name')+ will launch the application \verb+prog_name+ . It is
useful to execute an external PDE solver for instance especially under
Unix. It is not implemented for Macintosh because there is no simple way
to return to MacGfem after \texttt{progname} has ended.  
The same can be achieved  manually by a suitable combination of \verb+saveall+, \verb+wait+  and
\verb+load+  and simultaneous execution under multifinder.

\verb+user(what,f)+  calls the C++ function in a j-loop:
\begin{Verbatim}
for (int j=0; j<nquad, j++)
creal gfemuser( creal what, creal* f, int j)
\end{Verbatim}
\begin{itemize}

\item
\verb+creal+ is a scalar (\verb+float+ ) or a complex number if \verb+complex+  has
been set; \verb+nquad=3*nt+ if \verb+precise+  is set and \verb+ns+  otherwise. 

\item
\verb+what+  is intended for users who need several such functions.  
Then all can be put in the super function \verb+user+  and selection is by
an if statement on \verb+what+ .

\item
Within \verb+gfemuser+  access to all global variables are of course possible:
the triangulation (\verb+ns,nt, me, q, ng,ngt, area...+ ) ... refer to the file 
\verb+fem.C+  for more details.

\end{itemize}

\textbf{Remark}: An example of such gfemuser function is in \verb+fem.C+ ; if you
wish to put your own you must compile and link it.  Under Unix, it is
easy. Under the Macintosh system, either you use freefem, which is
Gfem's kernel, or you must ask us a library version of MacGfem.

%% language internals
%% node  Language internals,  , Other features, Generalities
\section{Language internals}
%%  node-name,  next,  previous,  up

\begin{itemize}
\item
Like most interpreters it has a lexical and a syntaxic part.  
In the lexical part the source is broken into tokens and recognized as 
symbols (see the enum symbol in the source file \texttt{lexical.h}).
For instance if the first character is a digit then it is a number and the
symbol type associated is \texttt{cste}.  This job is done by  function
\texttt{nextsym}.In addition it constructs a table of constants and variables
(which for convenience contains also the reserved words of the language).
\item
The lexical analyzer is a function called by the syntax analyzer. 
Hence the second is the main routine in the program except for a few 
initialization; it's name is \verb+instruction+ .The syntax analysis is
driven by the syntax rules because the language is LL(1).  Thus there
is C-function for each non-terminal.
\item
The program does not generate an object code but a tree.
For example,  parsing  \verb+x * y+ would generate a tree with root \verb+ * +   
and two branches \verb+x+ and \verb+y+ . Trees are C-struct with four pointers
for the 4 branches (here two would point to NULL) and a symbol for the
operator. The C-function which builds  trees is called \verb+plante+ .          
In the end the program is transformed into a full tree and 
to execute the program there is only one thing to do: evaluate
the operator at the root of the tree.
\item
The evaluation of the program is done by the C-function \verb+eval+ . It
looks at the root symbol and perform the corresponding operation. Here
it would do: \emph{return "value pointed by L1"*"value pointed by L2" if L1
and L2 where the addresses of the two branches}. 
\item
The art of the game is to associate a tree to each operation. For 
example when  the value of the variable \verb+x+  is required, this is also done 
by a tree which has   the operator "oldvar" as root.  The trickiest of all is 
the compound instruction \verb+{...;....};+ .  
Here \verb+{+  is considered as an operator with one branch on the current 
instruction and one branch on the next one.  Similarly for the 
\verb+ if...then... else+  instruction.

\end{itemize}

Suppose one wants to add an instruction to \textbf{freefem}, here is what must be
done:
\begin{itemize}
\item
Make sure the syntax is LL(1) and does not conflict with the old one. 
\item
Add reserved words to the table with \verb+installe+ . As there will be a
new Symbol, update the list of symbols (an enum structure). Add the
C-functions for the syntax analysis according  to the diagrams. Modify
eval by adding to the \verb+switch+  the new case. 
\end{itemize}

Here is the very simple structure we used for the nodes of the tree:
\begin{Verbatim}
typedef struct noeud
{
  Symbol symb; 
  creal value;
  ident *name;
  long  junk;
  char  *path;
  struct noeud *l1, *l2, *l3, *l4;
} noeud, *arbre;
\end{Verbatim}

%
%%%%%%%%%%%%% Some Settings for emacs and auc-TeX
% Local Variables:
% TeX-master: "freefem"
% TeX-parse-self: t
% TeX-auto-save: t
% TeX-auto-regexp-list: TeX-auto-full-regexp-list
% End:
%