%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Graphics output}%
\label{S:gfx}
\idx{graphics routines|(}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\ALBERTA provides one and two dimensional interactive graphic
subroutines built on the X--Windows and GL/OpenGL interfaces, and one,
two and three dimensional interactive graphics via the gltools
\cite{gltools}. Additionally, interfaces for
post--processing data with the GRAPE visualization environment \cite{Grape} 
as well as with the General Mesh Viewer \cite{GMV} are
supplied.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{One and two dimensional graphics subroutines}
\label{S:graph_1d2d}

A set of subroutines for opening, closing of graphic output
windows, and several display routines are provided, like drawing
the underlying mesh, displaying scalar finite element functions
as a graph in 1d, and using iso--lines or iso--colors in  2d. For vector
valued functions $\vec{v}$ similar routines are available, which display
the modulus $|\vec{v}|$.

The routines use the following type definitions for window identification,
color specification in [red, green, blue] coordinates, with
$0\leq \text{red, green, blue} \leq 1$, and standard colors
\ddx{GRAPH_WINDOW@{\code{GRAPH\_WINDOW}}}
\idx{graphics routines!GRAPH_WINDOW@{\code{GRAPH\_WINDOW}}}
\ddx{GRAPH_RGBCOLOR@{\code{GRAPH\_RGBCOLOR}}}
\idx{graphics routines!GRAPH_RGBCOLOR@{\code{GRAPH\_RGBCOLOR}}}
\cdx{rgb_black@{\code{rgb\_black}}}%
\idx{graphics routines!rgb_black@{\code{rgb\_black}}}%
\cdx{rgb_white@{\code{rgb\_white}}}%
\idx{graphics routines!rgb_white@{\code{rgb\_white}}}%
\cdx{rgb_red@{\code{rgb\_red}}}%
\idx{graphics routines!rgb_red@{\code{rgb\_red}}}%
\cdx{rgb_green@{\code{rgb\_green}}}%
\idx{graphics routines!rgb_green@{\code{rgb\_green}}}%
\cdx{rgb_blue@{\code{rgb\_blue}}}%
\idx{graphics routines!rgb_blue@{\code{rgb\_blue}}}%
\cdx{rgb_yellow@{\code{rgb\_yellow}}}%
\idx{graphics routines!rgb_yellow@{\code{rgb\_yellow}}}%
\cdx{rgb_magenta@{\code{rgb\_magenta}}}%
\idx{graphics routines!rgb_magenta@{\code{rgb\_magenta}}}%
\cdx{rgb_cyan@{\code{rgb\_cyan}}}%
\idx{graphics routines!rgb_cyan@{\code{rgb\_cyan}}}%
\cdx{rgb_grey50@{\code{rgb\_grey50}}}%
\idx{graphics routines!rgb_grey50@{\code{rgb\_grey50}}}%
\cdx{rgb_albert@{\code{rgb\_albert}}}%
\idx{graphics routines!rgb_albert@{\code{rgb\_albert}}}%
\cdx{rgb_alberta@{\code{rgb\_alberta}}}%
\idx{graphics routines!rgb_alberta@{\code{rgb\_alberta}}}%
\bv\begin{verbatim}
typedef void * GRAPH_WINDOW;

typedef float  GRAPH_RGBCOLOR[3];

extern const GRAPH_RGBCOLOR rgb_black; 
extern const GRAPH_RGBCOLOR rgb_white;  
extern const GRAPH_RGBCOLOR rgb_red;    
extern const GRAPH_RGBCOLOR rgb_green;  
extern const GRAPH_RGBCOLOR rgb_blue;   
extern const GRAPH_RGBCOLOR rgb_yellow; 
extern const GRAPH_RGBCOLOR rgb_magenta;
extern const GRAPH_RGBCOLOR rgb_cyan;   
extern const GRAPH_RGBCOLOR rgb_grey50; 

extern const GRAPH_RGBCOLOR rgb_albert;
extern const GRAPH_RGBCOLOR rgb_alberta;
\end{verbatim}\ev
%
The last two colors correspond to the two different colors in 
the \ALBERTA logo.

The following graphic routines are available for one and two dimensions:
\fdx{graph_open_window()@{\code{graph\_open\_window()}}}%
\idx{graphics routines!graph_open_window()@{\code{graph\_open\_window()}}}%
\fdx{graph_close_window()@{\code{graph\_close\_window()}}}%
\idx{graphics routines!graph_close_window()@{\code{graph\_close\_window()}}}%
\fdx{graph_clear_window()@{\code{graph\_clear\_window()}}}%
\idx{graphics routines!graph_clear_window()@{\code{graph\_clear\_window()}}}%
\fdx{graph_mesh()@{\code{graph\_mesh()}}}
\idx{graphics routines!graph_mesh()@{\code{graph\_mesh()}}}
\fdx{graph_drv()@{\code{graph\_drv()}}}
\idx{graphics routines!graph_drv()@{\code{graph\_drv()}}}
\fdx{graph_drv_d()@{\code{graph\_drv\_d()}}}
\idx{graphics routines!graph_drv_d()@{\code{graph\_drv\_d()}}}
\fdx{graph_el_est()@{\code{graph\_el\_est()}}}
\idx{graphics routines!graph_el_est()@{\code{graph\_el\_est()}}}
\fdx{graph_fvalues()@{\code{graph\_fvalues()}}}
\idx{graphics routines!graph_fvalues()@{\code{graph\_fvalues()}}}
\fdx{graph_line()@{\code{graph\_line()}}}
\idx{graphics routines!graph_line()@{\code{graph\_line()}}}
\fdx{graph_point()@{\code{graph\_point()}}}
\idx{graphics routines!graph_point()@{\code{graph\_point()}}}
\fdx{graph_points()@{\code{graph\_points()}}}
\idx{graphics routines!graph_points()@{\code{graph\_points()}}}
\bv\begin{verbatim}
GRAPH_WINDOW graph_open_window(const char *, const char *, REAL *, MESH *);
void graph_close_window(GRAPH_WINDOW);
void graph_clear_window(GRAPH_WINDOW, const GRAPH_RGBCOLOR);
void graph_mesh(GRAPH_WINDOW, MESH *, const GRAPH_RGBCOLOR, FLAGS);
void graph_drv(GRAPH_WINDOW, const DOF_REAL_VEC *, REAL, REAL, int);
void graph_drv_d(GRAPH_WINDOW, const DOF_REAL_D_VEC *, REAL, REAL, int);
void graph_el_est(GRAPH_WINDOW, MESH *, REAL (*)(EL *), REAL, REAL);
void graph_line(GRAPH_WINDOW, , const REAL [2], const REAL [2],
                const GRAPH_RGBCOLOR, REAL);
void graph_point(GRAPH_WINDOW, const REAL [2], const GRAPH_RGBCOLOR, float);
void graph_points(GRAPH_WINDOW, int, REAL (*)[2], const GRAPH_RGBCOLOR, float);
\end{verbatim}\ev
Description:
\begin{descr}
\kitem{graph\_open\_window(title, geometry, world, mesh)} the
  function re\-turns a pointer to a \code{GRAPH\_WINDOW} which is opened for
  display; if the window could not be opened, the return value is \nil;
  in 1d the $y$-direction of the graphic window is used for displaying the 
  graphs of functions;

\code{title} is an optional string holding a window title, if
\code{title} is \nil, a default title is used; \code{geometry} is an
optional string holding the window geometry in X11 format ``WxH'' or
``WxH+X+Y'', if \nil, a default geometry is used;

\code{world} is an optional pointer to an array of \emph{world
  coordinates} (xmin, xmax, ymin, ymax) to specify which part of a
   triangulation is displayed in this window, if \code{world} is
  \nil and \code{mesh} is not \nil, \code{mesh->diam} is used to select
  a range of world coordinates; in 1d, the range of the $y$-direction
  is set to $[-1,1]$; if both \code{world} and \code{mesh} are \nil, 
  the unit square $[0,1]\times[0,1]$ is displayed in 1d and 2d.

\kitem{graph\_close\_window(win)} closes the graphic window \code{win},
previously opened by the function \code{graph\_open\_window()}.

\kitem{graph\_clear\_window(win, c)} clears the graphic window 
\code{win} and sets the background color \code{c}; if \code{c}
is \nil, white is used as background color.

\kitem{graph\_mesh(win, mesh, c, flag)} displays the underlying 
\code{mesh} in the graphic window \code{win};
\code{c} is an optional color used for drawing lines, if \code{c} is \nil
black as a default color is used; the last argument
\code{flag} allows for a selection of an additional display; \code{flag}
may be \code{0} or the bitwise \textsf{OR} of some of the following flags:
\begin{descr}
\kitem{GRAPH\_MESH\_BOUNDARY}\cdx{GRAPH_MESH_BOUNDARY@{\code{GRAPH\_MESH\_BOUNDARY}}}
      only boundary edges are drawn, otherwise
      all edges of the triangulation are drawn;
      \code{c} is the display color for all edges if not \nil; otherwise
      the display color for Dirichlet boundary vertices/edges is
      blue and for Neumann vertices/edges the color is red; 
\kitem{GRAPH\_MESH\_ELEMENT\_MARK}\cdx{GRAPH_MESH_ELEMENT_MARK@{\code{GRAPH\_MESH\_ELEMENT\_MARK}}}
      triangles marked for refinement are filled red, and triangles marked for
      coarsening are filled blue, unmarked triangles are filled white;
\kitem{GRAPH\_MESH\_VERTEX\_DOF}\cdx{GRAPH_MESH_VERTEX_DOF@{\code{GRAPH\_MESH\_VERTEX\_DOF}}}
      the \emph{first\/}  DOF at each vertex is written near the vertex;
      currently only working in 2d when the library is not using OpenGL.
\kitem{GRAPH\_MESH\_ELEMENT\_INDEX}\cdx{GRAPH_MESH_ELEMENT_INDEX@{\code{GRAPH\_MESH\_ELEMENT\_INDEX}}}
     element indices are written inside the element, only available for
     \code{EL\_INDEX == 1};
     currently only working in 2d when the library is not using OpenGL.
\end{descr}

\kitem{graph\_drv(win, u, min, max, n\_refine)} displays the finite element
function stored in the \code{DOF\_REAL\_VEC} \code{u} in the graphic window 
\code{win}; in 1d, the graph
of $\code{u}$ is plotted in black, in 2d an iso-color display of \code{u}
is used; \code{min} and \code{max} specify a range of \code{u} which is 
displayed; if $\code{min} \geq \code{max}$, \code{min} and \code{max} of
\code{u} are computed by \code{graph\_drv()}; in 2d, coloring is adjusted
to the values of \code{min} and \code{max}; the display routine
always uses the linear interpolant on a simplex;  
if $\code{n\_refine} > 0$, each simplex is recursively bisected into 
$2^{\code{mesh->dim*n\_refine}}$ sub--simplices, and the linear interpolant
on these sub--simplices is displayed; for $\code{n\_refine} < 0$ the
default value \code{u->admin->bas\_fcts->degree-1} is used.

\kitem{graph\_drv\_d(win, v, min, max, n\_refine)} displays the
modulus of the vector valued finite element function stored in the
\code{DOF\_REAL\_D\_VEC} \code{v} in the graphic window \code{win};
the other arguments are the same as for \code{graph\_drv()}.

\kitem{graph\_el\_est(win, mesh, get\_el\_est)} displays
piecewise constant values over the triangulation \code{mesh}, 
like local error indicators, in the graphics window \code{win};
\code{get\_el\_est} is a pointer to a function which returns the 
constant value on each element; by this function the piecewise
constant function is defined.

\kitem{graph\_line(win, p0, p1, c, lw)} draws the line segment with
start point \code{p0} and end point \code{p1} in $(x,y)$ coordinates
in the graphic window \code{win}; \code{c} is an optional argument and
may specify the line color to be used; if \code{c} is \nil black is
used; \code{lw} specifies the linewidth (currently only for OpenGL
graphics); if $\code{lw} \leq 0$ the default linewidth \code{1.0} is
set.

\kitem{graph\_point(win, p, c, diam)} draws a point at the position \code{p}
in $(x,y)$ coordinates in the graphic window \code{win}; \code{c} is an
optional argument and may specify the color to be used; if \code{c} is \nil
black is used; \code{diam} specifies the drawing diameter (currently only for
OpenGL graphics); if $\code{diam} \leq 0$ the default diameter \code{1.0} is
set.

\kitem{graph\_points(win, np, p, c, diam)} draws a \code{np} points at the 
positions \code{p} in $(x,y)$ coordinates in the graphic window 
\code{win}; \code{c} is an
optional argument and may specify the color to be used; if \code{c} is \nil
black is used; \code{diam} specifies the drawing diameter (currently only for
OpenGL graphics); if $\code{diam} \leq 0$ the default diameter \code{1.0} is
set.
\end{descr}

\subsubsection{Graphic routines for two dimensions}\label{S:graph_2d}

The following routines are specialized routines for two dimensional
graphic output:
\fdx{graph_level_2d()@{\code{graph\_level\_2d()}}}
\idx{graphics routines!graph_level_2d()@{\code{graph\_level\_2d()}}}
\fdx{graph_levels_2d()@{\code{graph\_levels\_2d()}}}
\idx{graphics routines!graph_levels\_2d()@{\code{graph\_levels\_2d()}}}
\fdx{graph_level_d_2d()@{\code{graph\_level\_d\_2d()}}}
\idx{graphics routines!graph_level_d_2d()@{\code{graph\_level\_d\_2d()}}}
\fdx{graph_levels_d_2d()@{\code{graph\_levels\_d\_2d()}}}
\idx{graphics routines!graph_levels_d_2d()@{\code{graph\_levels\_d\_2d()}}}
\fdx{graph_fvalues_2d()@{\code{graph\_fvalues\_2d()}}}
\idx{graphics routines!graph_fvalues_2d()@{\code{graph\_fvalues\_2d()}}}
\bv\begin{verbatim}
void graph_level_2d(GRAPH_WINDOW, const DOF_REAL_VEC *, REAL,
                 const GRAPH_RGBCOLOR, int);
void graph_levels_2d(GRAPH_WINDOW, const DOF_REAL_VEC *, int, const REAL *,
                  const GRAPH_RGBCOLOR *, int);
void graph_level_d_2d(GRAPH_WINDOW, const DOF_REAL_D_VEC *, REAL,
                   const GRAPH_RGBCOLOR, int);
void graph_levels_d_2d(GRAPH_WINDOW, const DOF_REAL_D_VEC *, int, const REAL *,
                    const GRAPH_RGBCOLOR *, int);
void graph_fvalues_2d(GRAPH_WINDOW, MESH *, 
                      REAL (*)(const EL_INFO *, const REAL *),
                      FLAGS, REAL, REAL, int);
\end{verbatim}\ev

\begin{descr}
\kitem{graph\_level\_2d(win, v, level, c, n\_refine)} draws a single selected 
isoline at value \code{level} of the scalar finite element function
stored in the \code{DOF\_REAL\_VEC} \code{u} in the graphic window 
\code{win}; by the argument \code{c} a line color for the isoline can be
specified; if \code{c} is \nil, black is used as line color;
the display routine always uses the linear
interpolant of \code{u} on a simplex; if $\code{n\_refine} > 0$, each
triangle is recursively bisected into $2^{\code{2*n\_refine}}$
sub--triangles, and the selected isoline of the linear interpolant 
on these sub--triangles is displayed; for $\code{n\_refine} < 0$ the
default value \code{u->admin->bas\_fcts->degree-1} is used.

\kitem{graph\_levels\_2d(win, u, n, levels, c, n\_refine)} draws
\code{n} selected isolines at values \code{level[0]}, \dots, 
\code{level[n-1]} of the scalar finite element function
stored in the \code{DOF\_REAL\_VEC} \code{u} in the graphic window 
\code{win}; if \code{level} is \nil, \code{n} equally distant 
isolines between the minimum and maximum of \code{u} are selected;
\code{c} is an optional vector of \code{n} color values for the \code{n} 
isolines, if \nil, then default color values are used; the 
argument \code{n\_refine} again chooses a level of refinement,
where iso-lines of the piecewise linear interpolant is displayed;
for $\code{n\_refine} < 0$ the default value 
\code{u->admin->bas\_fcts->degree-1} is used.

\kitem{graph\_level\_d\_2d(win, v, level, c, n\_refine)} draws a single
selected isoline at values \code{level} of the modulus of a vector
valued finite element function stored in the \code{DOF\_REAL\_D\_VEC}
\code{v} in the graphic window \code{win}; the arguments are the same
as for \code{graph\_level()}.

\kitem{graph\_levels\_d\_2d(win, v, n, levels, c, n\_refine)} draws
\code{n} selected isolines at values \code{level[0]}, \dots, 
\code{level[n-1]} of the modulus of a vector valued finite element function
stored in the \code{DOF\_REAL\_D\_VEC} \code{v} in the graphic window 
\code{win}; the arguments are the same as for \code{graph\_levels()}.

\kitem{graph\_fvalues\_2d(win, mesh, f, flag, min, max, n\_refine)} displays 
the function \code{f} in the graphic window \code{win}; \code{f}
is a pointer to a function for evaluating values on single elements;
\code{f(el\_info, lambda)} returns the value of the function on
\code{el\_info->el} at the barycentric coordinates \code{lambda};

an iso-color display of \code{f} is used; \code{min} and \code{max} specify a 
range of \code{f} which is displayed; if $\code{min} \geq \code{max}$,
\code{min} and \code{max} of \code{f} are computed by
\code{graph\_fvalues\_2d()}; coloring is adjusted to the values of
\code{min} and \code{max}; the display routine always uses the linear
interpolant of \code{f} on a simplex; if $\code{n\_refine} > 0$, each
simplex is recursively bisected into $2^{\code{2*n\_refine}}$
sub--simplices, and the linear interpolant on these sub--simplices is
displayed.
\end{descr}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{gltools interface}\label{S:graph_gltools}%
\idx{gltools graphics|(}

The following interface for using the interactive gltools graphics of
WIAS Berlin \cite{gltools} is implemented. The gltools are freely
available under the  terms of the MIT license, see

\begin{flushleft}
\url{http://www.wias-berlin.de/software/gltools/}
\end{flushleft}

The \ALBERTA interface to the gltools is compatible with version
\code{gltools-2-4}.  It can be used for 1d, 2d, and 3d triangulation,
but only when \code{mesh->dim} equals \code{DIM\_OF\_WORLD}. For window
identification we use the data type
\idx{gltools graphics!GLTOOLS_WINDOW@{\code{GLTOOLS\_WINDOW}}}%
\ddx{GLTOOLS_WINDOW@{\code{GLTOOLS\_WINDOW}}}%
\idx{graphics routines!GLTOOLS_WINDOW@{\code{GLTOOLS\_WINDOW}}}%
\bv\begin{verbatim}
typedef void*    GLTOOLS_WINDOW;
\end{verbatim}\ev
The interface provides the following functions:
\fdx{open_gltools_window()@{\code{open\_gltools\_window()}}}%
\idx{gltools graphics!open_gltools_window()@{\code{open\_gltools\_window()}}}%
\idx{graphics routines!open_gltools_window()@{\code{open\_gltools\_window()}}}%
\fdx{close_gltools_window()@{\code{close\_gltools\_window()}}}%
\idx{gltools graphics!close_gltools_window()@{\code{close\_gltools\_window()}}}%
\idx{graphics routines!close_gltools_window()@{\code{close\_gltools\_window()}}}%
\idx{gltools graphics!gltools_mesh()@{\code{gltools\_mesh()}}}%
\idx{graphics routines!gltools_mesh()@{\code{gltools\_mesh()}}}%
\fdx{gltools_mesh()@{\code{gltools\_mesh()}}}%
\idx{gltools graphics!gltools_drv()@{\code{gltools\_drv()}}}%
\idx{graphics routines!gltools_drv()@{\code{gltools\_drv()}}}%
\fdx{gltools_drv()@{\code{gltools\_drv()}}}%
\idx{gltools graphics!gltools_drv_d()@{\code{gltools\_drv\_d()}}}%
\idx{graphics routines!gltools_drv_d()@{\code{gltools\_drv\_d()}}}%
\fdx{gltools_drv_d()@{\code{gltools\_drv\_d()}}}%
\idx{gltools graphics!gltools_vec()@{\code{gltools\_vec()}}}%
\idx{graphics routines!gltools_vec()@{\code{gltools\_vec()}}}%
\fdx{gltools_vec()@{\code{gltools\_vec()}}}%
\idx{gltools graphics!gltools_est()@{\code{gltools\_est()}}}%
\idx{graphics routines!gltools_est()@{\code{gltools\_est()}}}%
\fdx{gltools_est()@{\code{gltools\_est()}}}%
\idx{gltools graphics!gltools_disp_mesh()@{\code{gltools\_disp\_mesh()}}}%
\idx{graphics routines!gltools_disp_mesh()@{\code{gltools\_disp\_mesh()}}}%
\fdx{gltools_disp_mesh()@{\code{gltools\_disp\_mesh()}}}%
\idx{gltools graphics!gltools_disp_drv()@{\code{gltools\_disp\_drv()}}}%
\idx{graphics routines!gltools_disp_drv()@{\code{gltools\_disp\_drv()}}}%
\fdx{gltools_disp_drv()@{\code{gltools\_disp\_drv()}}}%
\idx{gltools graphics!gltools_disp_drv_d()@{\code{gltools\_disp\_drv\_d()}}}%
\idx{graphics routines!gltools_disp_drv_d()@{\code{gltools\_disp\_drv\_d()}}}%
\fdx{gltools_disp_drv_d()@{\code{gltools\_disp\_drv\_d()}}}%
\idx{gltools graphics!gltools_disp_vec()@{\code{gltools\_disp\_vec()}}}%
\idx{graphics routines!gltools_disp_vec()@{\code{gltools\_disp\_vec()}}}%
\fdx{gltools_disp_vec()@{\code{gltools\_disp\_vec()}}}%
\idx{gltools graphics!gltools_disp_est()@{\code{gltools\_disp\_est()}}}%
\idx{graphics routines!gltools_disp_est()@{\code{gltools\_disp\_est()}}}%
\fdx{gltools_disp_est()@{\code{gltools\_disp\_est()}}}%
\bv\begin{verbatim}
GLTOOLS_WINDOW open_gltools_window(const char *, const char *, const REAL *,
                                   MESH *, int);
void close_gltools_window(GLTOOLS_WINDOW);

void gltools_mesh(GLTOOLS_WINDOW, MESH *, int);
void gltools_drv(GLTOOLS_WINDOW, const DOF_REAL_VEC *, REAL, REAL);
void gltools_drv_d(GLTOOLS_WINDOW, const DOF_REAL_D_VEC *, REAL, REAL);
void gltools_vec(GLTOOLS_WINDOW, const DOF_REAL_D_VEC *, REAL, REAL);
void gltools_est(GLTOOLS_WINDOW, MESH *, REAL (*)(EL *), REAL, REAL);

void gltools_disp_mesh(GLTOOLS_WINDOW, MESH *, int, const DOF_REAL_VEC *);
void gltools_disp_drv(GLTOOLS_WINDOW, const DOF_REAL_VEC *, REAL, REAL,
                      const DOF_REAL_VEC *);
void gltools_disp_drv_d(GLTOOLS_WINDOW, const DOF_REAL_D_VEC *, REAL, REAL,
                      const DOF_REAL_VEC *);
void gltools_disp_vec(GLTOOLS_WINDOW, const DOF_REAL_D_VEC *, REAL, REAL,
                      const DOF_REAL_VEC *);
void gltools_disp_est(GLTOOLS_WINDOW, MESH *, REAL (*)(EL *), REAL, REAL,
                      const DOF_REAL_VEC *);
\end{verbatim}\ev
Description:
\begin{descr}
\kitem{open\_gltools\_window(title, geometry, world, mesh, dialog)}
       the function re\-turns a \code{GLTOOLS\_WINDOW} which is opened
       for display; if the window could not be opened, the return value
       is \nil; \code{title} is an optional string holding a title
       for the window; if \code{title} is \nil, a default is used;
       \code{geometry} is an optional string holding the window
       geometry in X11 format (``WxH'' or ``WxH+X+Y''), if \nil, a
       default geometry is used; the optional argument \code{world} is
       a pointer to an array of \emph{world coordinates} (xmin, xmax,
       ymin, ymax) for 2d and (xmin, xmax, ymin, ymax, zmin, zmax) for
       3d, it can be used to specify which part of the mesh will be
       displayed in the window; if \code{world} is \nil, either
       \code{mesh} or the default domain $[0,1]^{d}$ is used;
       \code{mesh} is an optional pointer to a mesh to select a range
       of world coordinates which will be displayed in the window; if
       both \code{world} and \code{mesh} are \nil, the default domain
       $[0,1]^{d}$ is used; display is not done or is done in
       an interactive mode depending on whether \code{dialog} equals \code{0}
       or not; in interactive mode type \code{'h'} to get a list of
       all key bindings;
\kitem{close\_gltools\_window(win)} closes the window \code{win}
        which has been previously opened by \code{open\_gltools\_window()};
\kitem{gltools\_mesh(win, mesh, mark)} displays the elements of \code{mesh} in
       the graphic window \code{win}; if \code{mark} is not zero 
       the piecewise constant function sign(\code{el->mark}) is
       shown;
       
\kitem{gltools\_drv(win, u, min, max)} displays the
       \code{DOF\_REAL\_VEC} \code{u} in the graphic window
       \code{win}; for higher order elements it is possible to display
       the vector on a refined grid; the key \code{'P'} toggles
       between refined and not refined mode; \code{min} and \code{max}
       define the range of the discrete function for display; if
       \code{min} $\geq$ \code{max} this range is adjusted
       automatically;

\kitem{gltools\_drv\_d(win, ud, min, max)} displays the modulus of the
       \code{DOF\_REAL\_D\_VEC} \code{ud} in the graphic window
       \code{win}; for higher order elements it is possible to display
       the vector on a refined grid; the key \code{'P'} toggles
       between refined and not refined mode; \code{min} and \code{max}
       define the range of the modulus of discrete function for display; if
       \code{min} $\geq$ \code{max} this range is adjusted
       automatically;

\kitem{gltools\_vec(win, ud, min, max)} displays the vector field given by
       \code{DOF\_REAL\_D\_VEC} \code{ud} in the graphic window
       \code{win}; for higher order elements it is possible to display
       the vector on a refined grid; the key \code{'P'} toggles
       between refined and not refined mode; \code{min} and \code{max}
       define the range of the modulus of discrete function for display; if
       \code{min} $\geq$ \code{max} this range is adjusted
       automatically;

\kitem{gltools\_est(win, mesh, get\_el\_est, min, max)} displays the 
       estimated error on \code{mesh} as a piecewise constant function
       in the graphic window \code{win}; the local indicators are accessed by
       \code{get\_el\_est()} on each element;
       \code{min} and \code{max} define the range for display; 
       if \code{min} $\geq$ \code{max} this range is adjusted automatically;

       \code{gltools\_est()} can also be used to display any piecewise
       constant function on the mesh, where local values are accessed by
       \code{get\_el\_est()};

\kitem{gltools\_disp\_mesh(win, mesh, mark, disp)} 
       additionally to \code{gltools\_mesh()}, a distortion of the
       geometry by a displacement vector field 
       \code{DOF\_REAL\_D\_VEC} \code{disp} is shown; this can be used in
       solid mechanics applications, e.g.;
\kitem{gltools\_disp\_drv(win, u, min, max, disp)} 
       similar to  \code{gltools\_drv()} but displayed on the 
       distorted geometry given by \code{DOF\_REAL\_D\_VEC} \code{disp};
\kitem{gltools\_disp\_drv\_d(win, ud, min, max, disp)} 
       similar to \code{gltools\_drv\_d()} but displayed on the 
       distorted geometry given by \code{DOF\_REAL\_D\_VEC} \code{disp};
\kitem{gltools\_disp\_vec(win, ud, min, max, disp)}
       similar to the function \code{gltools\_vec()} but displayed on the 
       distorted geometry given by \code{DOF\_REAL\_D\_VEC} \code{disp};
\kitem{gltools\_disp\_est(win, mesh, get\_el\_est, min, max, disp)}
       similar to the function \code{gltools\_est()} but displayed on the 
       distorted geometry given by \code{DOF\_REAL\_D\_VEC} \code{disp}.
 \end{descr}%
\idx{gltools graphics|)}

\subsection{GRAPE interface}\label{S:graph_GRAPE}%
\idx{GRAPE interface|(}

Visualization using the GRAPE library \cite{Grape} is only possible as
a post--processing step.  Data of the actual geometry and finite
element functions is written to file by \code{write\_mesh[\_xdr]()}
and \code{write\_dof\_real[\_d]\_vec[\_xdr]()} and then read by some
programs, using the GRAPE mesh interface for the visualization.  We
recommend using the \code{xdr} routines for portability of the stored
binary data.  The use of the GRAPE $h$--mesh and $hp$--mesh interfaces
is work in progress and the description of these programs will be done
in the near future.  References to visualization methods used in GRAPE
applying to \ALBERTA can be found in \cite{HORSS:03,RSS:95b,RSS:96}.

For obtaining the GRAPE library, please see
\begin{flushleft}
\url{http://www.iam.uni-bonn.de/sfb256/grape/}
\end{flushleft}

\idx{alberta_grape@{\code{alberta\_grape}}}
\idx{GRAPE interface!alberta_grape@{\code{alberta\_grape}}}
\idx{alberta_movi@{\code{alberta\_movi}}}
\idx{GRAPE interface!alberta_movi@{\code{alberta\_movi}}}
%%
The distribution of \ALBERTA contains source files with the
implementation of GRAPE mesh interface to \ALBERTA in the
\code{add\_ons/grape/} subdirectory. Having access to the GRAPE
library (Version 5.4.2), this interface can be compiled and linked
with the \ALBERTA and GRAPE library into the executables
\code{alberta\_grape??} and \code{alberta\_movi??}, where the
two-digit suffix \code{??} codes for the mesh-dimension and
\code{DIM\_OF\_WORLD}. Currently, however, only co-dimension $0$
versions in 2d and 3d are available.  The path of the GRAPE header
file and library has to be specified during the installation of
\ALBERTA, compare Section~\ref{S:install}.

The presence of the GRAPE library and header-file is determined at
configure time. If it is found, then the four GRAPE-programs are
compiled automatically when running \code{make} in the top-level
directory of the \ALBERTA distribution and installed below
\code{PREFIX/bin/} running \code{make install}

The program \code{alberta\_grape??} is mainly designed for displaying
finite element data on a single grid, i.\,e. one or several
scalar/vector-valued finite element functions on the corresponding
mesh.  \code{alberta\_grape??}  expects mesh data stored by
\code{write\_mesh[\_xdr]()} and \code{write\_dof\_real[\_xdr]()} or
\code{write\_dof\_real\_d[\_xdr]()} defined on the same mesh.
\bv\begin{lstlisting}
 alberta_grape22 -m mesh.xdr -s scalar.xdr -v vector.xdr
\end{lstlisting}\ev
will display the 2d mesh stored in the file \code{mesh.xdr} 
together with the scalar finite element function stored in 
\code{scalar.xdr} and the vector valued finite element function
stored in \code{vector.xdr}.

\code{alberta\_grape?? --help} gives some online-help, including a
short example:
%%
\bv\begin{verbatim}
jane_john_doe@street ~ $ 
jane_john_doe@street ~ $ alberta_grape33 --help
Usage: alberta_grape33 [-p PATH] [OPTIONS]
          -m  MESH [-s DRV] [-v DRDV] [[-m MESH1] [-s DRV1] [-v DRDV1] ...]

Example:
 alberta_grape33 --mesh=mymesh -s temperature --vector velocity

    where "mymesh", "temperature" and "velocity" are file-names.

If a long option shows an argument as mandatory, then it is mandatory
for the equivalent short option also.  Similarly for optional arguments.

The order of the options _is_ significant in the following cases:
`-p PATH' alters the search path for all following data-files.
`-m MESH' specifies a new mesh for all following DRVs and DRDVs (see below)

Options:
  -m, --mesh=MESH
            The file-name of an ALBERTA-mesh gnereated by the ALBERTA
            library routines `write_mesh()' or `write_mesh_xdr()'
            `-x' and `-b' options below.
            This option is mandatory and may not be omitted. This option
            may be specified multiple times. All following dof-vectors
            given by the `-s' and `-v' options must belong to the most
            recently specified mesh.
  -b, --binary
            Expect MESH, DRV and DRDV to contain data in host dependent
            byte-order, generated by `write_SOMETHING()' routines of the
            ALBERTA library (SOMETHING is `mesh', `dof_real_vec' etc.
  -x, --xdr
            This is the default and just mentioned here for completeness.
            Expect MESH, DRV and DRDV to contain data in network
            byte-order, generated by `write_SOMETHING_xdr()' routines
            of the ALBERTA library. Per convention this means big-endian
            byte-order.
  -s, --scalar=DRV
            Load the data-file DRV which must contain a DOF_REAL_VEC
            dumped to disk by `write_dof_real_vec[_xdr]()'.
            This option may be specified multiple times. The DOF_REAL_VECs
            must belong to the most recently specified mesh.
            See `-m' and `-b' above.
  -v, --vector=DRDV
            Load the data-file DRDV which must contain a DOF_REAL_VEC_D
            dumped to disk by `write_dof_real_d_vec[_xdr]()'.
            This option may be specified multiple times. The vector
            must belong to the most recently specified mesh.
            See `-m' and `-b' above.
  -p, --path=PATH
            Specify a path prefix for all following data-files. This option
            may be specified multiple times. PATH is supposed to be the
            directory containing all data-files specified by the following
            `-m', `-s' and `-v' options.
  -h, --help
            Print this help.
\end{verbatim}\ev

The program \code{alberta\_movi??} is designed for displaying finite
element data on a sequence of grids with one or several
scalar/vector-valued finite element functions. This is the standard
visualization tool for post--processing data from time--dependent
simulations. \code{alberta\_movi??}
expects a sequence of mesh data stored by \code{write\_mesh[\_xdr]()} and
finite element data of this mesh stored by
\code{write\_dof\_real[\_xdr]()} or
\code{write\_dof\_real\_d[\_xdr]()},
where the filenames for the sequence of meshes and finite element
functions are generated by the function \code{generate\_filename()},
explained in \secref{S:generate_filename}. Section~\ref{S:heat_timestep}
shows how to write such a sequence of data in a time-dependent
problem. 

Similar to \code{alberta\_grape??} the command
\code{alberta\_movi?? --help} gives some online-help:
%%
\bv\begin{verbatim}
jane_john_doe@street ~ $ 
jane_john_doe@street ~ $ alberta_movi33 --help
Usage: alberta_movi33 START END [-p PATH] [OPTIONS]
          -m  MESH [-s DRV] [-v DRDV] [[-s DRV1] [-v DRDV1] ...]

Example:
  alberta_movi33 --mesh=mymesh 0 10 -i 5 -s u_h --vector v_h

  reads grid mesh000000 with scalar function u_h000000 and
  vector function v_h000000, then mesh000005 with u_h000005 and
  v_h000005, and finally mesh000010 with u_h000010 and v_h000010

If a long option shows an argument as mandatory, then it is mandatory
for the equivalent short option also.  Similarly for optional arguments.

The order of the options is not significant with the exception that the
non-option arguments START and END must come _first_.

Non-option arguments:
  START END
            Two integers specifying the start- and end-scene. The actual
            file names of the data-files are generated by appending a six
            digit number which loops between START and END.
            See also `-i' below.
Options:
  -i, --increment=INC
            INC is an integers specifying the increment while reading in
            the time scenes. To read e.g. only every second time-scene
            use `-i 2'. INC defaults to 1
  -m, --mesh=MESH
            The file-name prefix of an ALBERTA-mesh gnereated by the ALBERTA
            library routines `write_mesh()' or `write_mesh_xdr()'
            `-x' and `-b' options below. The actual file name is generated
            by appending a six digit time-scene number to MESH, unless
            the `-f' option is also specified, see below.
            This option is mandatory and may not be omitted.
  -f, --fixed-mesh
            Use a single fixed mesh for all time-scenes (i.e. in the
            non-adaptive case). If `-f' is used `-m MESH' gives the actual
            file name of the mesh and not only the mesh-prefix. See `-m'
            above.
  -s, --scalar=DRV
            Load the data-files DRVXXXXXX which must contain DOF_REAL_VECs
            dumped to disk by `write_dof_real_vec[_xdr]()'.
            `XXXXXX' stands for the time-scene number.
            This option may be specified multiple times. The DOF_REAL_VECs
            must belong to the meshes specified with the `-m' option.
            See `-m', `-b', `-p' and `-i'.
  -v, --vector=DRDV
            Load the data-files DRDVXXXXXX which contain DOF_REAL_VEC_Ds
            dumped to disk by `write_dof_real_d_vec[_xdr]()'.
            `XXXXXX' stands for the time-scene number.
            This option may be specified multiple times. The vectors
            must belong to the meshes specified with the `-m' option.
            See `-m', `-b', `-p' and `-i'.
  -p, --path=PATH
            Specify a path prefix for all data-files. PATH is supposed to
            be the directory containing all data-files specified by the
            `-m', `-s' and `-v' options.
  -B, --Bar
            Generate a time-progress-bar when displaying the data in GRAPE.
  -b, --binary
            Expect MESH, DRV and DRDV to contain data in host dependent
            byte-order, generated by `write_SOMETHING()' routines of the
            ALBERTA library (SOMETHING is `mesh', `dof_real_vec' etc.
  -x, --xdr
            This is the default and just mentioned here for completeness.
            Expect MESH, DRV and DRDV to contain data in network
            byte-order, generated by `write_SOMETHING_xdr()' routines
            of the ALBERTA library. Per convention this means big-endian
            byte-order.
  -h, --help
            Print this help.
\end{verbatim}\ev

\idx{GRAPE interface|)}

\subsection{Paraview interface}
\label{S:graph_paraview}
\label{S:graph_Paraview}
\idx{Paraview interface|(}
%%
The Paraview interface (\url{http://www.paraview.org/}) -- like the
GRAPE-interface -- is available as a set of separate programs which
can be used to display finite element data in a post-processing step.
The corresponding programs do not require any support package and are
always compiled when running \code{make} and installed below
\code{PREFIX/bin/} when running \code{make install}. The programs are
named \code{alberta2paraview2d} and \code{alberta2paraview3d}. The
calling convention is somewhat similar to the GRAPE support-programs,
and running the programs with the \code{--help} command-line switch
displays an online-help, including some simple examples:
%%
\bv\begin{verbatim}
jane_john_doe@street ~ $ 
jane_john_doe@street ~ $ alberta2paraview3d --help
Usage: alberta2paraview3d [-t FIRST LAST] [-i STEP] [-p PATH] [-o OUTPUT]
          -m  MESH [-s DRV] [-v DRDV] [[-m MESH1] [-s DRV1] [-v DRDV1] ...]

Example for converting stationary data:
  alberta2paraview3d \
       -r lagrange_degree --mesh mymesh -s temperature --vector velocity
    where "mymesh", "temperature" and "velocity" are file-names.

Example for converting a sequence of files resulting from a transient
problem:
  alberta2paraview3d -t 0 10 -i 5 -p PATH --mesh mymesh -s u_h --vector v_h

  reads grid mymesh000000 with scalar function u_h000000 and
  vector function v_h000000, then mesh000005 with u_h000005 and
  v_h000005, and finally mesh000010 with u_h000010 and v_h000010

If a long option shows an argument as mandatory, then it is mandatory
for the equivalent short option also.  Similarly for optional arguments.

The order of the options _is_ significant in the following cases:
`-p PATH' alters the search path for all following data-files.
`-m MESH' specifies a new mesh for all following DRVs and DRDVs (see below)
`-b|-x'   alters the expected data-format for all following files
          (see below)

Options:
  -t, --transient FIRST LAST
            Convert a sequence of mesh- and data-files. The file-names
            must end with 6-digit decimal number. FIRST and LAST specify the
            first and last member of this sequence.
  -i, --interval SKIP
            In conjunction with `-t' use only every SKIP-th frame in the
            given sequence of files.
  -m, --mesh MESH
            The file-name of an ALBERTA-mesh gnereated by the ALBERTA
            library routines `write_mesh()' or `write_mesh_xdr()'
            `-x' options below.
            This option is mandatory and may not be omitted. This option
            may be specified multiple times. All following dof-vectors
            given by the `-s' and `-v' options must belong to the most
            recently specified mesh.
  -a, --ascii
            Write the paraview file in ASCII format.
  -r, --refined LAGRANGE-DEGREE
            Expect Lagrange-degree (between 0 and 4) to refine the given
            MESH
            To select 'no refinement' simply do not specify `--refined',
            'Lagrange-degree = 0' is the default.
  -u, --unperforated
            For a 3d mesh refine without holes (produces a lot more
            elements). To select mesh-refine with holes simply do not
            specify `--unperforated' (refinement with holes is the default).
  -b, --binary
            Write the paraview file in binary format.
            To select ASCII OUTPUT format simply do not specify `--binary',
            because ASCII OUTPUT format is the default.
  -x, --xdr
            This is the default and just mentioned here for completeness.
            Expect MESH, DRV and DRDV to contain data in network
            byte-order, generated by `write_SOMETHING_xdr()' routines
            of the ALBERTA library. Per convention this means big-endian
            byte-order. '-l' and '-x' may be specified multiple times.

  -l, --legacy
            Expect MESH, DRV and DRDV to contain data in ALBERTA's
            legacy file-format, generated by `write_SOMETHING()' routines
            of the ALBERTA library. This may not work, because the format
            of those data-files is byte-order dependent and thus not portable
            across different computer architectures. '-l' and '-x' may be
            specified multiple times.
  -s, --scalar DRV
            Load the data-file DRV which must contain a DOF_REAL_VEC
            dumped to disk by `write_dof_real_vec[_xdr]()'.
            This option may be specified multiple times. The DOF_REAL_VECs
            must belong to the most recently specified mesh.
            See `-m' above.
  -v, --vector DRDV
            Load the data-file DRDV which must contain a DOF_REAL_VEC_D
            dumped to disk by `write_dof_real_d_vec[_xdr]()'.
            This option may be specified multiple times. The vector
            must belong to the most recently specified mesh.
            See `-m' above.
  -o, --output FILENAME
            Specify an output file-name. If this option is omitted, then the
            output file-name is"alberta".
  -d, --pvd_output FILENAME
            Specify an pvd_output file-name,in conjuncion with'-t'.
             "alberta_paraview_movi"is the default
  -p, --path PATH
            Specify a path prefix for all following data-files. This option
            may be specified multiple times. PATH is supposed to be the
            directory containing all data-files specified by the following
            `-m', `-s' and `-v' options.
  -h, --help
            Print this help.

\end{verbatim}\ev
%%
\idx{Paraview interface|)}%

\subsection{Geomview interface}
\label{S:graph_Geomview}
\idx{Geomview interface|(}
%%
Geomview (\url{http://www.geomview.org/}) is a quite ancient rendering
engine, originally developed by the Geometry Center
(\url{http://www.geom.uiuc.edu/}). It is easy to use, but as such not
a visualization tool for finite element data, and mainly aiming at
displaying 2-surfaces. Currently, Geomview is the only way to directly
visualize 2d and 3d simulations with co-dimension larger than $1$,
respectively $0$. The suite of demo-programs contains a rudimentary
interface to Geomview, the use is demonstrated in the demo-programs
using parametric meshes, like \code{src/Common/ellipt-sphere.c}.
%%
\idx{Geomview interface|)}%

\subsection{GMV interface}
\label{S:graph_GMV}%
\idx{GMV interface|(}

A second possibility to visualize \ALBERTA meshes and vectors as a 
post--processing step is to use the General Mesh Viewer (GMV) developed 
at the Los Alamos National Laboratories. For information on how to obtain
this program see
\begin{flushleft}
\url{http://www-xdiv.lanl.gov/XCM/gmv/GMVHome.html}
\end{flushleft}
GMV is a standalone program and support for the GMV interface in \ALBERTA 
is always built in. At the moment, this interface is the only one which 
supports all of the following features: embedded meshes 
(\code{mesh->dim < DIM\_OF\_WORLD}), parametric meshes, generation of movie
sequences, reusing meshes for several vectors to reduce disk space, and 
several more. The \ALBERTA interface was written for GMV 4.0.

The interface contains the following functions:

\fdx{write_mesh_gmv()@{\code{write\_mesh\_gmv()}}}
\idx{graphics routines!write_mesh_gmv()@{\code{write\_mesh\_gmv()}}}
\fdx{write_dof_vec_gmv()@{\code{write\_dof\_vec\_gmv()}}}
\idx{graphics routines!write_dof_vec_gmv()@{\code{write\_dof\_vec\_gmv()}}}
\bv\begin{verbatim}
int write_mesh_gmv(MESH *, const char *, int, int, const int, 
                   DOF_REAL_VEC **, const int, DOF_REAL_D_VEC **,
                   DOF_REAL_D_VEC *, REAL)

int write_dof_vec_gmv(MESH *, const char *, const char *, int, int, const int,
                      DOF_REAL_VEC **drv_ptr, const int, DOF_REAL_D_VEC **,
                      DOF_REAL_D_VEC *, REAL);
\end{verbatim}\ev
Description:
\begin{descr}
\kitem{write\_mesh\_gmv(mesh,name,asc,ref,n\_drv,drvs,n\_drdv,drdvs,vel,time)}
Writes an \ALBERTA triangulation and DOF vectors into a file \code{name} 
readable by the GMV program. The parameter \code{asc}, if set to \true
directs \ALBERTA to write the data in GMV ASCII format, otherwise a native
binary format is used. The triangulation is stored in \code{mesh}. The 
parameters \code{n\_drv} and \code{n\_drdv} state the number of 
\code{DOF\_REAL\_VEC}s and \code{DOF\_REAL\_D\_VEC}s to store in the file. 
These vectors are passed as arrays of pointers \code{drvs} and \code{drdvs}.
At the moment there is a limit of 250 vectors of either type which may 
be written at once. The additional argument \code{vel} is used for one 
\code{DOF\_REAL\_D\_VEC} which has the meaning of a velocity field. This 
results in a special treatment by GMV; GMV will automatically create a 
new field storing the velocity magnitudes on reading the file. The 
argument \code{time} stores a time value for instationary simulations.

As most other visualization packages, GMV
is only able to display linear data. To alleviate this problem, the parameter 
\code{ref}, if set to \true, directs the interface to output
a virtually refined triangulation to avoid loss of data when visualizing 
higher order Lagrange DOF vectors. This only works for Lagrange finite 
element spaces.
\kitem{write\_dof\_vec\_gmv(mesh,mfile,name,asc,ref,n\_drv,drvs,n\_drdv,drdvs,vel,time)}
This routine works in a similar way as \code{write\_mesh\_gmv()}. The only 
difference is that the mesh triangulation is not output into the file. Instead,
\ALBERTA generates a GMV file containing a reference to another GMV file 
\code{mfile} containing the mesh. The mesh file must have been output 
previously using \code{write\_mesh\_gmv()}. No refinement or coarsening must
occur between these calls, otherwise GMV will be unable to use the old mesh.

The advantage of this is that disk space is saved, since there is no need to 
repeatedly write entire mesh triangulations for instationary simulations 
without mesh changes. This also saves time on reading the GMV file.
\end{descr}
\idx{GMV interface|)}%
\idx{graphics routines|)}


%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "alberta-man"
%%% End: