\section{Direct sums of finite element spaces}%
\label{S:chain_impl}

Sometimes it is necessary to use finite element spaces which are
direct sums of a standard space plus a more or less bizarre add-on.
The velocity space for several stable mixed discretizations of the
Stokes problem, for instance, has this structure: it consists of
piece-wise linear elements plus an element bubble for the so-called
``Mini''-element, piece-wise linear elements plus face-bubbles for the
``Bernardi-Raugel''-element, for the ``Crouzeix-Raviart'' element it
consists of piece-wise quadratic elements plus an element-bubble in
2d, and forms a direct sum with three components in 3d, where
face-bubble have to be added in addition to the element-bubble, which
was already present in 2d.

\subsection{Data structures for disjoint unions and direct sums }
\ALBERTA support such direct sums of finite element spaces. The
fundaments for such direct sums are formed by ``chains'' of
\code{BAS\_FCTS}-structures, modeling the disjoint union of local
basis-function sets, see \secref{S:bfcts_chains}. A disjoint union of
basis functions sets is implemented using a cyclic, doubly linked
list.  This affects all structures which are functionally based on the
structure of the local set of basis functions: the
\code{FE\_SPACE}-structure, the \code{DOF\_XXX\_VEC} coefficient
vectors, and their local counter parts name \code{EL\_XXX\_VEC}
(\code{XXX} being used as a place holder for the type, e.g. \code{XXX}
$\equiv$ \code{REAL}), the matrix structure \code{DOF\_MATRIX} (and
its local count-part), the frame-work used for assembling the discrete
systems and -- of course -- the quadrature caches defined by the
\code{QUAD\_FAST} structure.  Basically, all structures which are
directly of indirectly derived from such a disjoint union of local
basis function sets inherit this ``disjoint union'' layout and come
with a list-node component which implements this connectivity within
\ALBERTA. The list node itself is a simple doubly-linked list node,
namely
%%
\bv\begin{lstlisting}
typedef struct dbl_list_node DBL_LIST_NODE;

struct dbl_list_node
{
  struct dbl_list_node *next;
  struct dbl_list_node *prev;
};
\end{lstlisting}\ev
%
In all the structures needing such a list-node, there are components
named \code{\dots chain}, compare for instance the source code listing
for the \code{BAS\_FCTS} structure on page \pageref{T:BAS_FCTS}:
%%
\bv\begin{lstlisting}
struct bas_fcts
{
  ... /* other stuff */
  DBL_LIST_NODE chain;
  ... /* more stuff */
};
\end{lstlisting}\ev
%%
This becomes even more complicated in the context of
matrix-structures, the \code{EL\_MATRIX} structure (compare the
source-code listing on page \pageref{T:EL_MATRIX}), for instance,
needs two list-node components, namely
%%
\bv\begin{lstlisting}
struct el_matrix
{
  ... /* other stuff */
  DBL_LIST_NODE row_chain;
  DBL_LIST_NODE col_chain;
  ... /* more stuff */
};
\end{lstlisting}\ev
%%
because the local row-space as well as the local column-space may be
direct sums of local finite element spaces. So matrices carry a
block-matrix structure if the underlying spaces are direct sums, and
the \code{col\_chain} and \code{row\_chain} give the link between the
different blocks, each block being a single \code{EL\_MATRIX}
structure (or whatever other matrix-structure).

Conceptionally, all these lists are \emph{cyclic}, and there is no
dedicated list-head. This may bear the risk for certain kinds of
programming errors, but is, on the other hand, quite nice for the
implementation, because in this setting an ordinary \code{BAS\_FCTS}
structure which is not a disjoint union of several basis function sets
is at the same time a disjoint union with one component, so the code
does not need to differentiate between direct sums and
single-component objects, thus eliminating the need to introduce new
data-types to model direct sums of function spaces.

\subsection{List-management and looping constructs}
\label{S:chain_loops}

This section describes some basic support macro and functions for
list-management like adding to direct sum or deleting from them, as
well as some loop-constructs. Generally, all the macros come in three
flavours: with a \code{CHAIN\_\dots}-, \code{ROW\_CHAIN\_\dots} and a
\code{COL\_CHAIN\_\dots} prefix, acting on the \code{chain},
\code{row\_chain} and \code{col\_chain} list-nodes in the respective
data-structures. This is the only difference between the three
flavours of macros, so we describe only the variant with the
\code{CHAIN}-prefix.

\mdx{CHAIN_INIT()@{\code{CHAIN\_INIT()}}}%
\mdx{CHAIN_INITIALIZER()@{\code{CHAIN\_INITIALIZER()}}}%
\mdx{CHAIN_LENGTH()@{\code{CHAIN\_LENGTH()}}}%
\mdx{CHAIN_SINGLE()@{\code{CHAIN\_SINGLE()}}}%

\mdx{CHAIN_NEXT()@{\code{CHAIN\_NEXT()}}}%
\mdx{CHAIN_PREV()@{\code{CHAIN\_PREV()}}}%
\mdx{CHAIN_ADD_HEAD()@{\code{CHAIN\_ADD\_HEAD()}}}%
\mdx{CHAIN_ADD_TAIL()@{\code{CHAIN\_ADD\_TAIL()}}}%
\mdx{CHAIN_DEL()@{\code{CHAIN\_DEL()}}}%

\mdx{CHAIN_FOREACH()@{\code{CHAIN\_FOREACH()}}}%
\mdx{CHAIN_FOREACH_SAVE()@{\code{CHAIN\_FOREACH\_SAVE()}}}%
\mdx{CHAIN_FOREACH_REV()@{\code{CHAIN\_FOREACH\_REV()}}}%
\mdx{CHAIN_FOREACH_REV_SAVE()@{\code{CHAIN\_FOREACH\_REV\_SAVE()}}}%

\mdx{CHAIN_DO()@{\code{CHAIN\_DO()}}}%
\mdx{CHAIN_WHILE()@{\code{CHAIN\_WHILE()}}}%
\mdx{CHAIN_DO_REV()@{\code{CHAIN\_DO\_REV()}}}%
\mdx{CHAIN_WHILE_REV()@{\code{CHAIN\_WHILE\_REV()}}}%

\mdx{FOREACH_DOF()@{\code{FOREACH\_DOF()}}}%
\mdx{FOREACH_DOF_DOW()@{\code{FOREACH\_DOF\_DOW()}}}%
\mdx{FOREACH_FREE_DOF()@{\code{FOREACH\_FREE\_DOF()}}}%
\mdx{FOREACH_FREE_DOF_DOW()@{\code{FOREACH\_FREE\_DOF\_DOW()}}}%

\begin{descr}
  \kitem{CHAIN\_INIT(elem)} Initialize \code{elem->chain}; that is
  make \code{elem->chain.next} and \code{elem->chain.prev} to
  \code{\&elem->chain}. This defines the empty, respectively
  one-component list.
  %% 
  \kitem{CHAIN\_INITIALIZER(name)} Perform the same task as
  \code{CHAIN\_INIT(elem)}, but in the context of a static
  initialization, e.g.
  \bv\begin{lstlisting}
static BAS\_FCTS bfcts = {
  ... /* other stuf */,
  CHAIN_INITIALIZER(bfcts),
  ... /* more stuff */
};    
  \end{lstlisting}\ev
  %%
  \kitem{CHAIN\_LENGTH(head)} Compute the number of list elements in
  the cyclic list \code{head->chain}.
  %%
  \kitem{CHAIN\_SINGLE(var)} Evaluate to \code{true} if
  \code{var->chain} is the one-element list.
  %%
  \kitem{CHAIN\_NEXT(var, type)} \kitem{CHAIN\_PREV(var, type)} Return
  a pointer to the element following, respectively preceding
  \code{var}. The argument \code{type} must denote the data-type of
  \code{var}, e.g.
  %% 
  \bv\begin{lstlisting}
    const BAS_FCTS *next_bfcts = CHAIN_NEXT(bfcts, const BAS_FCTS);
    const BAS_FCTS *prev_bfcts = CHAIN_PREV(bfcts, const BAS_FCTS);
  \end{lstlisting}\ev
  %%
  \kitem{CHAIN\_ADD\_HEAD(head, elem)} \kitem{CHAIN\_ADD\_TAIL(head,
    elem)} Add \code{elem} to the head, respectively to the tail of
  \code{head->chain}. Adding to the head means that \code{elem} will
  become the element \emph{following} \code{head}, and adding to the
  tail means that \code{elem} will become the list element preceding
  \code{head}. In particular, adding to either the end or tail of an
  one-element list will produce the same results.
  %% 
  \kitem{CHAIN\_DEL(elem)} Delete \code{elem->chain} from any list it
  may belong to, and call \code{CHAIN\_INIT(elem)} afterwards. The
  result will be that \code{elem} becomes a one-element list.
  %%
  \kitem{CHAIN\_FOREACH(ptr, head, type)} Loop over all element of
  \code{head->chain} which follow \code{head->chain}, excluding the
  element pointed to by \code{head} itself. Something similar to
  \code{CHAIN\_LENGTH(head)} mentioned above could for instance be
  implemented as
  %%
  \bv\begin{lstlisting}
int bfcts_chain_length(const BAS_FCTS *head)
{
  const BAS_FCTS *pos;

  int len = 1;
  CHAIN_FOREACH(pos, head, const BAS_FCTS) {
    ++len;
  }
  return len;
}
  \end{lstlisting}\ev
  %%
  \kitem{CHAIN\_FOREACH\_SAVE(ptr, next, head, type)} Similar to
  \code{CHAIN\_FOREACH()}, but allow for deletion of list-elements
    during the loop. For this to work an additional pointer has to be
    provided which is points to the element following the current
    element. This way, the current element -- \code{pos} -- maybe
    safely removed from the list and deleted during the loop:
    %%
    \bv
    \begin{lstlisting}
typedef struct my_chained_object
{
  ... /* stuff */
  DBL_LIST_NODE chain;
  ... /* other suff */
};

int delete_my_chained_object(MY_CHAINED_OBJECT *list)
{
  MY_CHAINED_OBJECT *pos, *next;

  CHAIN_FOREACH_SAFE(pos, next, list, MY_CHAINED_OBJECT) {
    CHAIN_DEL(pos);
    MEM_FREE(pos, 1, MY_CHAINED_OBJECT);
  }
  MEM_FREE(head, 1, MY_CHAINED_OBJECT);
}
    \end{lstlisting}
    \ev
    %%
    \kitem{CHAIN\_FOREACH\_REV(ptr, head, type)}
    \kitem{CHAIN\_FOREACH\_REV\_SAVE(ptr, next, head, type)} Same as
    the non-\code{REV}-counterparts explained above, but the loop is
    perform in the reverse direction, following
    \code{head->chain.prev} instead of \code{head->chain.next}.
    %%
    \kitem{CHAIN\_DO(list, type)} \kitem{CHAIN\_WHILE(list, type)}
    Perform a loop over the list, include the first element (in
    contrast to \code{CHAIN\_FOREACH()} which always skips the first
    element:
    \bv\begin{lstlisting}
int bfcts_chain_length(const BAS_FCTS *pos)
{
  int len = 0;
  CHAIN_DO(pos, const BAS_FCTS) {
    ++len;
  } CHAIN_WHILE(pos, const_BAS_FCTS);
  return len;
}
    \end{lstlisting}\ev
    %% 
    \kitem{CHAIN\_DO\_REV(list, type)} \kitem{CHAIN\_WHILE\_REV(list,
      type)} Same as the \code{CHAIN\_DO()}-\code{CHAIN\_WHILE()}
    pair, but loop in reverse direction, following
    \code{list->head.prev} instead of \code{list->head.next}.
    %%
    \kitem{FOREACH\_DOF(fe\_space, todo, next)} A replacement for
    \code{FOR\_ALL\_DOFS()}, which implements an outer loop over the
    components of the chain, calling \code{FOR\_ALL\_DOFS()} for each
    component in turn. In this setting \code{todo} is a code-block
    which is executed for each \code{DOF} and \code{next} is a code
    block which is executed at the end of the inner
    \code{FOR\_ALL\_DOFS()} call and should be used to roll data to
    the next chain-component. The first argument is moved on to
    Compare also \secref{S:FOR_ALL_DOFS}. Example:
    \bv\begin{lstlisting}
void print_all_values(const DOF_REAL_VEC *dof_vec)
{
  FOREACH_DOF(dof_vec->fe_space,
              /* todo-block*/
              MSG("value: %e\n", dof_vec->vec[dof]),
              /* next-block */
              dof_vec = CHAIN_NEXT(dof_vec, const DOF_REAL_VEC));
}
    \end{lstlisting}\ev
    %% 
    \kitem{FOREACH\_DOF\_DOW(fe\_space, todo, todo\_cart, next)} A
    special version of \code{FOREACH\_DOF()} for chains mixing
    vector-valued finite element functions based on either scalar- or
    \DOW-valued basis functions: in this context the coefficient
    vectors for scalar basis functions consist of vector valued
    coefficients, while the coefficient vectors for scalar
    basis-functions consist of scalars, e.g.
    \bv\begin{lstlisting}
void print_all_values_dow(const DOF_REAL_VEC_D *dof_vec)
{
  FOREACH_DOF_DOW(dof_vec->fe_space,
              /* todo-block*/
              MSG("value: %e\n", dof_vec->vec[dof]),
              /* todo_cart-block */
              MSG("value: "FORMAT_DOW"\n",
                  EXPAND_DOW(((const DOF_REAL_D_VEC *)dof_vec)->vec[dof])),
              /* next-block */
              dof_vec = CHAIN_NEXT(dof_vec, const DOF_REAL_VEC_D));
}
    \end{lstlisting}\ev
    Note the difference between a \code{DOF\_REAL\_VEC\_D} coding a
    vector valued finite-element function, and a
    \code{DOF\_REAL\_D\_VEC}, coding for a vector storing
    \code{REAL\_D}-valued coefficients. The name \code{todo\_cart}
    stems from the fact that the parts of the direct sum belonging to
    scalar-valued basis functions is in fact a Cartesian product space
    of scalar finite element spaces.
    %% 
    \kitem{FOREACH\_FREE\_DOF(fe\_space, todo, next)}
    %%
    \kitem{FOREACH\_FREE\_DOF\_DOW(fe\_space, todo, todo\_cart, next)}
    %%
    Similar to the other two loop-macros, but in the inner loop the
    \code{FOR\_ALL\_FREE\_DOFS)}-macro is called, see
    \secref{S:FOR_ALL_DOFS}.
\end{descr}

\subsection{Managing temporary coefficient vectors}
\label{S:dof_vec_skel}

Sometimes it is useful to hook a contiguous, flat array of values into
a ``dummy'' \code{DOF\_XXX\_VEC} structure. Most iterative solver
available from third party sources, for instance, as well as the
``OEM''-library functions (Orthogonal Error Methods, see
\secref{S:solver}) expect matrix-vector routines which accept pointers
to such arrays, but the matrix-vector routines implementing the
operation of \code{DOF\_MATRIX}es on finite element coefficient
vectors only accept arguments of type
\code{DOF\_REAL[\_D]\_VEC[\_D]}-type (see \secref{S:DOF_BLAS}).

\begin{compatibility}
  \label{compat:dof_skeletons}
  Prior to the introduction of the support for direct sums of finite
  element spaces, this task was quite easy, have a look at the
  following code-excerpt, implementing a matrix-vector routine for an
  \emph{older} version of \ALBERTA:
  %%
  \bv\begin{lstlisting}
void mat_vec_s(void *ud, int dim, const REAL *x, REAL *y)
{
  DOF_REAL_VEC  dof_x = {nil, nil, "x", 0, nil, nil, nil};
  DOF_REAL_VEC  dof_y = {nil, nil, "y", 0, nil, nil, nil};
  struct mv_data  *data     = (struct mv_data *)ud;
  const DOF_ADMIN *admin    = data->matrix->row_fe_space->admin;

  dof_x.fe_space = data->matrix->col_fe_space;
  dof_y.fe_space = data->matrix->row_fe_space;
  dof_x.size = dof_y.size = dim;
  dof_x.vec = (REAL *) x;
  dof_y.vec = y;

  dof_mv(data->transpose, data->matrix, &dof_x, &dof_y);
}
  \end{lstlisting}\ev
  However, this will no longer work, because the \code{dof\_mv()}
  routine expects its argument to model direct sums of finite element
  spaces, and even for the standard case it expects the
  \code{dof\_x.chain} and \code{dof\_y.chain} list-nodes to be
  initialized properly, defining ``direct sums'' consisting of a
  single summand.
\end{compatibility}

To aid the task of defining such ``dummy''-vectors, there are some
support functions which take care of transferring the
direct-sum-structure of the finite element space in question to the
temporaries which are needed to interface, e.g., to the matrix-vector
routines pairing \code{DOF\_MATRIX}es with \code{DOF}-vectors. To
improve the readability of the code, it is maybe advisable to use the
new routines anyway. The example given above in
\compatref{compat:dof_skeletons} collapses to the following, using the
routines explained further below:
%%
\bv\begin{lstlisting}
void mat_vec_s(void *ud, int dim, const REAL *x, REAL *y)
  struct mv_data *data = (struct mv_data *)ud;
  DOF_REAL_VEC *dof_x = data->x_skel;
  DOF_REAL_VEC *dof_y = data->y_skel;

  distribute_to_dof_real_vec_skel(data->x_skel, x);
  distribute_to_dof_real_vec_skel(data->y_skel, y);

  dof_mv(data->transpose, data->matrix, data->mask, dof_x, dof_y);
}
\end{lstlisting}\ev

Well, it spares only a few lines. But on the other hand, prescribing
an API for tasks like this increases portability between different
versions of \ALBERTA, because only with such an API it is possible to
hide the more ``dirty'' details, or future extensions, from
application programs. We continue with the description of the
available functions. The example program for the non-linear reaction
diffusion program contained in the demo-package (and described in
\secref{S:nonlin-impl} also makes use of these support functions.

\pagebreak[2]
\begin{samepage}
The available functions are as follows:
%%
\fdx{dof_real_vec_length()@{\code{dof\_real\_vec\_length()}}}%
\fdx{dof_real_d_vec_length()@{\code{dof\_real\_d\_vec\_length()}}}%
\fdx{dof_real_vec_d_length()@{\code{dof\_real\_vec\_d\_length()}}}%
%%
\fdx{init_dof_real_vec_skel()@{\code{init\_dof\_real\_vec\_skel()}}}%
\fdx{init_dof_real_d_vec_skel()@{\code{init\_dof\_real\_d\_vec\_skel()}}}%
\fdx{init_dof_real_vec_d_skel()@{\code{init\_dof\_real\_vec\_d\_skel()}}}%
\fdx{init_dof_schar_vec_skel()@{\code{init\_dof\_schar\_vec\_skel()}}}%
%%
\fdx{get_dof_real_vec_skel()@{\code{get\_dof\_real\_vec\_skel()}}}%
\fdx{get_dof_real_d_vec_skel()@{\code{get\_dof\_real\_d\_vec\_skel()}}}%
\fdx{get_dof_real_vec_d_skel()@{\code{get\_dof\_real\_vec\_d\_skel()}}}%
\fdx{get_dof_schar_vec_skel()@{\code{get\_dof\_schar\_vec\_skel()}}}%
%%
\fdx{distribute_to_dof_real_vec_skel()@{\code{distribute\_to\_dof\_real\_vec\_skel()}}}%
\fdx{distribute_to_dof_real_d_vec_skel()@{\code{distribute\_to\_dof\_real\_d\_vec\_skel()}}}%
\fdx{distribute_to_dof_real_vec_d_skel()@{\code{distribute\_to\_dof\_real\_vec\_d\_skel()}}}%
\fdx{distribute_to_dof_schar_vec_skel()@{\code{distribute\_to\_dof\_schar\_vec\_skel()}}}%
%%
\fdx{copy_to_dof_real_vec()@{\code{copy\_to\_dof\_real\_vec()}}}%
\fdx{copy_to_dof_real_d_vec()@{\code{copy\_to\_dof\_real\_d\_vec()}}}%
\fdx{copy_to_dof_real_vec_d()@{\code{copy\_to\_dof\_real\_vec\_d()}}}%
\fdx{copy_to_dof_schar_vec()@{\code{copy\_to\_dof\_schar\_vec()}}}%
%%
\fdx{copy_from_dof_real_vec()@{\code{copy\_from\_dof\_real\_vec()}}}%
\fdx{copy_from_dof_real_d_vec()@{\code{copy\_from\_dof\_real\_d\_vec()}}}%
\fdx{copy_from_dof_real_vec_d()@{\code{copy\_from\_dof\_real\_vec\_d()}}}%
\fdx{copy_from_dof_schar_vec()@{\code{copy\_from\_dof\_schar\_vec()}}}%
\begin{lstlisting}
size_t dof_real_vec_d_length(const FE_SPACE *fe_space);
size_t dof_real_d_vec_length(const FE_SPACE *fe_space);
size_t dof_real_vec_length(const FE_SPACE *fe_space);
    
DOF_REAL_VEC *init_dof_real_vec_skel(DOF_REAL_VEC vecs[],
                                     const char *name,
                                     const FE_SPACE *fe_space);
DOF_REAL_D_VEC *init_dof_real_d_vec_skel(DOF_REAL_D_VEC vecs[],
                                         const char *name,
                                         const FE_SPACE *fe_space);
DOF_REAL_VEC_D *init_dof_real_vec_d_skel(DOF_REAL_VEC_D vecs[],
                                         const char *name,
                                         const FE_SPACE *fe_space);
DOF_SCHAR_VEC *init_dof_schar_vec_skel(DOF_SCHAR_VEC vecs[],
                                       const char *name,
                                       const FE_SPACE *fe_space);

DOF_REAL_VEC *get_dof_real_vec_skel(const char *name,
                                    const FE_SPACE *fe_space,
                                    SCRATCH_MEM scr);
DOF_REAL_D_VEC *get_dof_real_d_vec_skel(const char *name,
                                        const FE_SPACE *fe_space,
                                        SCRATCH_MEM scr);
DOF_REAL_VEC_D *get_dof_real_vec_d_skel(const char *name,
                                        const FE_SPACE *fe_space,
                                        SCRATCH_MEM scr);
DOF_SCHAR_VEC *get_dof_schar_vec_skel(const char *name,
                                      const FE_SPACE *fe_space,
                                      SCRATCH_MEM scr);

void distribute_to_dof_real_vec_skel(DOF_REAL_VEC *skel, const REAL *data);
void distribute_to_dof_real_d_vec_skel(DOF_REAL_D_VEC *skel, const REAL *_data);
void distribute_to_dof_real_vec_d_skel(DOF_REAL_VEC_D *skel, const REAL *data);
void distribute_to_dof_schar_vec_skel(DOF_SCHAR_VEC *skel, const S_CHAR *data);

void copy_to_dof_real_vec(DOF_REAL_VEC *vecs, const REAL *data);
void copy_to_dof_real_d_vec(DOF_REAL_D_VEC *vecs, const REAL *_data);
void copy_to_dof_real_vec_d(DOF_REAL_VEC_D *vecs, const REAL *data);
void copy_to_dof_schar_vec(DOF_SCHAR_VEC *vecs, const S_CHAR *data);

void copy_from_dof_real_vec(REAL *data, const DOF_REAL_VEC *vecs);
void copy_from_dof_real_d_vec(REAL_D *data, const DOF_REAL_D_VEC *vecs);
void copy_from_dof_real_vec_d(REAL *data, const DOF_REAL_VEC_D *vecs);
void copy_from_dof_schar_vec(S_CHAR *data, const DOF_SCHAR_VEC *vecs);
\end{lstlisting}
\end{samepage}

Descriptions for each of the functions listed above:
\begin{description}
\label{desc:dof_real_vec_length}
%%
\fdx{dof_real_vec_length()@{\code{dof\_real\_vec\_length()}}}%
\fdx{dof_real_d_vec_length()@{\code{dof\_real\_d\_vec\_length()}}}%
\fdx{dof_real_vec_d_length()@{\code{dof\_real\_vec\_d\_length()}}}%
%%
\item[Synopsis]~\hfill

\begin{lstlisting}
length = dof_real_vec_d_length(fe_space);
length = dof_real_d_vec_length(fe_space);
length dof_real_vec_length(fe_space);
\end{lstlisting}
\item[Description]~\hfill

  Compute the total dimension of \code{fe\_space}.
\item[Parameters]~\hfill
  \begin{descr}
    \kitem{fe\_space} The finite element space to compute the
    dimension of.
  \end{descr}
\item[Return Value]~\hfill

  The total dimension of the direct sum of finite element spaces. Note
  that vector-valued coefficients are counted with their
  \DOW-multiplicity. The return value is of type \code{size\_t}.
\end{description}

\hrulefill

\begin{description}
\label{desc:init_dof_real_vec_skel}
%%
\fdx{init_dof_real_vec_skel()@{\code{init\_dof\_real\_vec\_skel()}}}%
\fdx{init_dof_real_d_vec_skel()@{\code{init\_dof\_real\_d\_vec\_skel()}}}%
\fdx{init_dof_real_vec_d_skel()@{\code{init\_dof\_real\_vec\_d\_skel()}}}%
\fdx{init_dof_schar_vec_skel()@{\code{init\_dof\_schar\_vec\_skel()}}}%
%%
\item[Synopsis]~\hfill
\begin{lstlisting}
head_vec = init_dof_real_vec_skel(&dof_vec_storage[0], name, fe_space);
head_vec = init_dof_real_d_vec_skel(&dof_vec_storage[0], name, fe_space);
head_vec = init_dof_real_vec_d_skel(&dof_vec_storage[0], name, fe_space);
head_vec = init_dof_schar_vec_skel(&dof_vec_storage[0], name, fe_space);
\end{lstlisting}
\item[Description]~\hfill

  Turn an uninitialized storage area consisting of sufficiently many
  \code{DOF\_REAL[\_D]\_VEC[\_D]} or \code{DOF\_SCHAR\_VEC} objects
  and turn it into a concatenated list, describing a coefficient
  vector for the finite element space specified by \code{fe\_space}.
  The resulting dof-vectors are, of course, not hooked into the lists
  of \code{fe\_space->admin}, and are not subject to automatic
  resizing during mesh adaptation. Further, they do not carry storage
  for data, i.e. their \code{vec} component does not point to a valid
  storage area (but see \code{distribute\_to\_dof\_XXX\_vec\_skel()}
  below).  Therefore we call the resulting object a ``skeleton'',
  which also explains the name of this function.
\item[Arguments]~\hfill
  \begin{descr}
    \kitem{dof\_vec\_storage} Pointer to a storage area, pointing to
    sufficiently many DOF-vectors, stored consecutively in memory
    (i.e. \code{dof\_vec\_storage} is a flat array of sufficient
    size). The number of the objects needed can be determined by
    calling \code{CHAIN\_LENGTH(fe\_space)}.
    %%
    \kitem{name} A descriptive name for the skeleton. It is hooked
    into the \code{name} component of each of the individual DOF-vectors.
    %%
    \kitem{fe\_space} The underlying finite element space.
    \code{fe\_space} determines the layout of the resulting chained
    coefficient vector.
  \end{descr}
\item[Return Value]~\hfill

  The first component of the multi-component coefficient vector.
\end{description}

\hrulefill

\begin{description}
\label{desc:get_dof_real_vec_skel}
%%
\fdx{get_dof_real_vec_skel()@{\code{get\_dof\_real\_vec\_skel()}}}%
\fdx{get_dof_real_d_vec_skel()@{\code{get\_dof\_real\_d\_vec\_skel()}}}%
\fdx{get_dof_real_vec_d_skel()@{\code{get\_dof\_real\_vec\_d\_skel()}}}%
\fdx{get_dof_schar_vec_skel()@{\code{get\_dof\_schar\_vec\_skel()}}}%
%%
\item[Synopsis]~\hfill
\begin{lstlisting}
head_vec = get_dof_real_vec_skel(name, fe_space, scr);
head_vec = get_dof_real_d_vec_skel(name, fe_space, scr);
head_vec = get_dof_real_vec_d_skel(name, fe_space, scr);
head_vec = get_dof_schar_vec_skel(name, fe_space, scr);
\end{lstlisting}
\item[Description]~\hfill

Allocate and initialize a temporary DOF-vector from a scratch-memory pool, see
\secref{S:scratch_memory}. This functionally equivalent to
\begin{lstlisting}
DOF_REAL_VEC *get_dof_real_vec_skel(const char *name,
				    const FE_SPACE *fe_space,
				    SCRATCH_MEM scr)
{
  DOF_REAL_VEC *vecs;
  
  vecs = SCRATCH_MEM_ALLOC(scr, CHAIN_LENGTH(fe_space), DOF_REAL_VEC);

  return init_dof_real_vec_skel(vecs, name, fe_space);
}
\end{lstlisting}
Likewise for the other types of DOF-vectors.

\item[Arguments]~\hfill
  \begin{descr}
    \kitem{name} Symbolic name.
    %%
    \kitem{fe\_space} The underlying finite element space.
    %%
    \kitem{scr} Pointer to a scratch-memory pool, see
    \secref{S:scratch_memory}. Consequently, the objects generated here
    can and will be destroyed when the scratch-memory pool is deleted
    by calling \code{SCRATCH\_MEM\_ZAP(scr)}.
  \end{descr}
\item[Return Value]~\hfill

A pointer to the head of the chain.  
\end{description}

\hrulefill

\begin{description}
\label{desc:distribute_to_dof_real_vec_skel}
%%
\fdx{distribute_to_dof_real_vec_skel()@{\code{distribute\_to\_dof\_real\_vec\_skel()}}}%
\fdx{distribute_to_dof_real_d_vec_skel()@{\code{distribute\_to\_dof\_real\_d\_vec\_skel()}}}%
\fdx{distribute_to_dof_real_vec_d_skel()@{\code{distribute\_to\_dof\_real\_vec\_d\_skel()}}}%
\fdx{distribute_to_dof_schar_vec_skel()@{\code{distribute\_to\_dof\_schar\_vec\_skel()}}}%
%%
\item[Synopsis]~\hfill

\begin{lstlisting}
distribute_to_dof_real_vec_skel(dof_vec_skel, contiguous_data);
distribute_to_dof_real_d_vec_skel(dof_vec_skel, contiguous_data);
distribute_to_dof_real_vec_d_skel(dof_vec_skel, contiguous_data);
distribute_to_dof_schar_vec_skel(dof_vec_skel, contiguous_data);
\end{lstlisting}
\item[Description]~\hfill

  Distribute a contiguous piece of data specified by
  \code{contiguous\_data} to a DOF-vector skeleton as generated by a
  call to \code{get\_dof\_XXX\_vec\_skel()} or
  \code{init\_dof\_XXX\_vec\_skel()} described above. ``Distribute''
  in this context means to initialize the \code{vec} component of each
  part of the DOF-vector chain with the proper location into
  \code{contiguous\_data}. The data will be distributed to the
  individual components according to the dimension of the component of
  the finite element space they belong to.

  This function must be called prior to passing a DOF-vector skeleton
  to any function expecting a ``real'' DOF-vector.

  To only copy data between contiguous arrays and DOF-vectors, see
  \code{copy\_to|from\_dof\_XXX\_vec()} below.
\item[Arguments]~\hfill
  \begin{descr}
    \kitem{dof\_vec\_skel} The DOF-vector skeleton.
    %%
    \kitem{contiguous\_data} A piece of contiguous data with
    \code{dof\_XXX\_vec\_length(fe\_space)} many items.    
  \end{descr}
\end{description}

\hrulefill

\begin{description}
\label{desc:copy_to_dof_real_vec}
%%
\fdx{copy_to_dof_real_vec()@{\code{copy\_to\_dof\_real\_vec()}}}%
\fdx{copy_to_dof_real_d_vec()@{\code{copy\_to\_dof\_real\_d\_vec()}}}%
\fdx{copy_to_dof_real_vec_d()@{\code{copy\_to\_dof\_real\_vec\_d()}}}%
\fdx{copy_to_dof_schar_vec()@{\code{copy\_to\_dof\_schar\_vec()}}}%
%%
\item[Synopsis]~\hfill

\begin{lstlisting}
copy_to_dof_real_vec(dof_vec, contiguous_data);
copy_to_dof_real_d_vec(dof_vec, contiguous_data);
copy_to_dof_real_vec_d(dof_vec, contiguous_data);
copy_to_dof_schar_vec(dof_vec, contiguous_data);
\end{lstlisting}
\item[Description]~\hfill

  Copy data from a flat array containing at least
  \code{dof\_XXX\_vec\_length()} many items to a DOF-vector object,
  taking care of the chained structure of coefficient vectors
  belonging to direct sums of finite element spaces.

  This function will overwrite all the data stored in \code{dof\_vec}.
\item[Arguments]~\hfill
  \begin{descr}
    \kitem{dof\_vec} The destination of the copy operation.
    \kitem{contiguous\_data} The source of the copy operation.
  \end{descr}
\item[Return Value]~\hfill
  
\end{description}

\hrulefill

\begin{description}
\label{desc:copy_from_dof_real_vec}
%%
\fdx{copy_from_dof_real_vec()@{\code{copy\_from\_dof\_real\_vec()}}}%
\fdx{copy_from_dof_real_d_vec()@{\code{copy\_from\_dof\_real\_d\_vec()}}}%
\fdx{copy_from_dof_real_vec_d()@{\code{copy\_from\_dof\_real\_vec\_d()}}}%
\fdx{copy_from_dof_schar_vec()@{\code{copy\_from\_dof\_schar\_vec()}}}%
\item[Synopsis]~\hfill

\begin{lstlisting}
copy_from_dof_real_vec(contiguous_data, dof_vec);
copy_from_dof_real_d_vec(contiguous_data, dof_vec);
copy_from_dof_real_vec_d(contiguous_data, dof_vec);
copy_from_dof_schar_vec(contiguous_data, dof_vec);
\end{lstlisting}
\item[Description]~\hfill

  Copy data from a DOF-vector to a flat array containing at least
  \code{dof\_XXX\_vec\_length()} many items, taking care of the
  chained structure of coefficient vectors belonging to direct sums of
  finite element spaces.

  This function will overwrite all the data stored in \code{contiguous\_data}.
\item[Arguments]~\hfill
  \begin{descr}
    \kitem{contiguous\_data} Destination of the copy operation.
    \kitem{dof\_vec} Source of the copy operation.
  \end{descr} 
\item[Return Value]~\hfill
  
\end{description}

\subsection{Data transfer during mesh adaptation}
\label{S:chained_coarse_refine_inter}

If the underlying finite element space is indeed a direct sum, then it
is an inconvenient task to install the default refinement and
coarsening functions into each component of the chain. For a
single-component sum, the following suffices:
%%
\begin{lstlisting}
extern DOF_REAL_VEC_D *vector;

vector->refine_inter = vector->fe_space->bas_fcts->real_refine_inter_d;
\end{lstlisting}
%%
However, if \code{vector} is only the first part of a chain, then the
following elements of the chain are not touched by this operation, one
would have to do something similar to the following:
%%
\begin{lstlisting}
extern DOF_REAL_VEC_D *vector;

CHAIN_DO(uh,DOF_REAL_VEC_D) {
  uh->refine_interpol = uh->fe_space->bas_fcts->real_refine_inter_d;
} CHAIN_WHILE(uh, DOF_REAL_VEC_D);
\end{lstlisting}
%%
There are small inline functions defined through the inclusion which
perform just this, above code, e.g., is wrapped into the following
function:
%%
\begin{lstlisting}
static inline void set_refine_inter_dow(DOF_REAL_VEC_D *uh)
{
  CHAIN_DO(uh,DOF_REAL_VEC_D) {
    uh->refine_interpol = uh->fe_space->bas_fcts->real_refine_inter_d;
  } CHAIN_WHILE(uh, DOF_REAL_VEC_D);
}
\end{lstlisting}
%%
As the code is self-explaining (at least after reading
\secref{S:chain_loops} and \secref{S:DOF_INTERPOL}), we only list the
proto-types here:
%%
\fdx{set_refine_inter@{\code{set\_refine\_inter()}}}
\fdx{set_refine_inter_d@{\code{set\_refine\_inter\_d()}}}
\fdx{set_refine_inter_dow@{\code{set\_refine\_inter\_dow()}}}
%%
\fdx{set_coarse_inter@{\code{set\_coarse\_inter()}}}
\fdx{set_coarse_inter_d@{\code{set\_coarse\_inter\_d()}}}
\fdx{set_coarse_inter_dow@{\code{set\_coarse\_inter\_dow()}}}
%%
\fdx{set_coarse_restrict@{\code{set\_coarse\_restrict()}}}
\fdx{set_coarse_restrict_d@{\code{set\_coarse\_restrict\_d()}}}
\fdx{set_coarse_restrict_dow@{\code{set\_coarse\_restrict\_dow()}}}
%%
\begin{lstlisting}
static inline void set_refine_inter(DOF_REAL_VEC *uh);
static inline void set_refine_inter_d(DOF_REAL_D_VEC *uh);
static inline void set_refine_inter_dow(DOF_REAL_VEC_D *uh);

static inline void set_coarse_inter(DOF_REAL_VEC *uh);
static inline void set_coarse_inter_d(DOF_REAL_D_VEC *uh);
static inline void set_coarse_inter_dow(DOF_REAL_VEC_D *uh);

static inline void set_coarse_restrict(DOF_REAL_VEC *uh);
static inline void set_coarse_restrict_d(DOF_REAL_D_VEC *uh);
static inline void set_coarse_restrict_dow(DOF_REAL_VEC_D *uh);
\end{lstlisting}

\subsection{Forming direct sub-sums}
\label{S:sub_chains}

Sometimes it is handy to refer only to selected components of a chain
of objects. The following routines perform this task by forming
sub-chains of objects, which then belong to a direct sub-sum, so to
say:

\fdx{bas_fcts_sub_chain()@{\code{bas\_fcts\_sub\_chain()}}}%
\fdx{fe_space_sub_chain()@{\code{fe\_space\_sub\_chain()}}}%
%%
\fdx{dof_real_vec_sub_chain()@{\code{dof\_real\_vec\_sub\_chain()}}}%
\fdx{dof_real_d_vec_sub_chain()@{\code{dof\_real\_d\_vec\_sub\_chain()}}}%
\fdx{dof_real_vec_d_sub_chain()@{\code{dof\_real\_vec\_d\_sub\_chain()}}}%
\fdx{dof_dof_vec_sub_chain()@{\code{dof\_dof\_vec\_sub\_chain()}}}%
\fdx{dof_int_vec_sub_chain()@{\code{dof\_int\_vec\_sub\_chain()}}}%
\fdx{dof_uchar_vec_sub_chain()@{\code{dof\_uchar\_vec\_sub\_chain()}}}%
\fdx{dof_schar_vec_sub_chain()@{\code{dof\_schar\_vec\_sub\_chain()}}}%
\fdx{dof_ptr_vec_sub_chain()@{\code{dof\_ptr\_vec\_sub\_chain()}}}%
%%
\fdx{dof_matrix_sub_chain()@{\code{dof\_matrix\_sub\_chain()}}}%
%%
\fdx{update_dof_real_vec_sub_chain()@{\code{update\_dof\_real\_vec\_sub\_chain()}}}%
\fdx{update_dof_real_d_vec_sub_chain()@{\code{update\_dof\_real\_d\_vec\_sub\_chain()}}}%
\fdx{update_dof_real_vec_d_sub_chain()@{\code{update\_dof\_real\_vec\_d\_sub\_chain()}}}%
\fdx{update_dof_dof_vec_sub_chain()@{\code{update\_dof\_dof\_vec\_sub\_chain()}}}%
\fdx{update_dof_int_vec_sub_chain()@{\code{update\_dof\_int\_vec\_sub\_chain()}}}%
\fdx{update_dof_uchar_vec_sub_chain()@{\code{update\_dof\_uchar\_vec\_sub\_chain()}}}%
\fdx{update_dof_schar_vec_sub_chain()@{\code{update\_dof\_schar\_vec\_sub\_chain()}}}%
\fdx{update_dof_ptr_vec_sub_chain()@{\code{update\_dof\_ptr\_vec\_sub\_chain()}}}%
%%
\fdx{update_dof_matrix_sub_chain()@{\code{update\_dof\_matrix\_sub\_chain()}}}%
\fdx{update_bas_fcts_sub_chain()@{\code{update\_bas\_fcts\_sub\_chain()}}}%
\fdx{update_fe_space_sub_chain()@{\code{update\_fe\_space\_sub\_chain()}}}%
\begin{lstlisting}
BAS_FCTS *bas_fcts_sub_chain(SCRATCH_MEM scr, const BAS_FCTS *bas_fcts,
                             FLAGS which);
void update_bas_fcts_sub_chain(BAS_FCTS *bas_fcts);
FE_SPACE *fe_space_sub_chain(SCRATCH_MEM scr, const FE_SPACE *fe_space,
                             FLAGS which);
void update_fe_space_sub_chain(FE_SPACE *fe_space);

DOF_REAL_VEC *dof_real_vec_sub_chain(SCRATCH_MEM scr,
                                     const DOF_REAL_VEC *vec,
                                     FLAGS which);
DOF_REALD_VEC *dof_real_d_vec_sub_chain(SCRATCH_MEM scr,
                                        const DOF_REAL_D_VEC *vec,
                                        FLAGS which);
DOF_REAL_VEC_D *dof_real_vec_d_sub_chain(SCRATCH_MEM scr,
                                         const DOF_REAL_VEC_D *vec,
                                         FLAGS which);
DOF_DOF_VEC *dof_dof_vec_sub_chain(SCRATCH_MEM scr,
                                   const DOF_DOF_VEC *vec,
                                   FLAGS which);
DOF_INT_VEC *dof_int_vec_sub_chain(SCRATCH_MEM scr,
                                   const DOF_INT_VEC *vec,
                                   FLAGS which);
DOF_UCHAR_VEC *dof_uchar_vec_sub_chain(SCRATCH_MEM scr,
                                       const DOF_UCHAR_VEC *vec,
                                       FLAGS which);
DOF_SCHAR_VEC *dof_schar_vec_sub_chain(SCRATCH_MEM scr,
                                       const DOF_SCHAR_VEC *vec,
                                       FLAGS which);
DOF_PTR_VEC *dof_ptr_vec_sub_chain(SCRATCH_MEM scr,
                                   const DOF_PTR_VEC *vec,
                                   FLAGS which);

void update_dof_real_vec_sub_chain(const DOF_REAL_VEC *sub_vec);
void update_dof_real_d_vec_sub_chain(const DOF_REAL_D_VEC *sub_vec);
void update_dof_real_vec_d_sub_chain(const DOF_REAL_VEC_D *sub_vec);
void update_dof_dof_vec_sub_chain(const DOF_DOF_VEC *sub_vec);
void update_dof_int_vec_sub_chain(const DOF_INT_VEC *sub_vec);
void update_dof_uchar_vec_sub_chain(const DOF_UCHAR_VEC *sub_vec);
void update_dof_schar_vec_sub_chain(const DOF_SCHAR_VEC *sub_vec);
void update_dof_ptr_vec_sub_chain(const DOF_PTR_VEC *sub_vec);


DOF_MATRIX *dof_matrix_sub_chain(SCRATCH_MEM scr, const DOF_MATRIX *A,
                                 FLAGS row_which, FLAGS col_which);
void update_dof_matrix_sub_chain(DOF_MATRIX *sub_M);
\end{lstlisting}

The general idea is to make shallow copies of selected components of
the original chain, shallow in the sense that the copies share the
underlying data (e.g. such a shallow copy of a \code{DOF\_REAL\_VEC}
would share the \code{vec} component with the original instance).
Those copies are then chained-together, forming sub-chains. The
selection of the components is performed by means of a bit-mask,
called \code{which} in the proto-types listed above. If bit $n$ in the
\code{which}-mask is set, then the component number $n$ takes part in
forming the sub-chain. Analogously for matrices where we need a two
masks, one for the rows, and another one for the columns of the
block-matrix.

Descriptions for the individual groups of functions:

\begin{description}
\fdx{bas_fcts_sub_chain()@{\code{bas\_fcts\_sub\_chain()}}}%
\fdx{fe_space_sub_chain()@{\code{fe\_space\_sub\_chain()}}}%
%%
\fdx{dof_real_vec_sub_chain()@{\code{dof\_real\_vec\_sub\_chain()}}}%
\fdx{dof_real_d_vec_sub_chain()@{\code{dof\_real\_d\_vec\_sub\_chain()}}}%
\fdx{dof_real_vec_d_sub_chain()@{\code{dof\_real\_vec\_d\_sub\_chain()}}}%
\fdx{dof_dof_vec_sub_chain()@{\code{dof\_dof\_vec\_sub\_chain()}}}%
\fdx{dof_int_vec_sub_chain()@{\code{dof\_int\_vec\_sub\_chain()}}}%
\fdx{dof_uchar_vec_sub_chain()@{\code{dof\_uchar\_vec\_sub\_chain()}}}%
\fdx{dof_schar_vec_sub_chain()@{\code{dof\_schar\_vec\_sub\_chain()}}}%
\fdx{dof_ptr_vec_sub_chain()@{\code{dof\_ptr\_vec\_sub\_chain()}}}%
%%
\fdx{dof_matrix_sub_chain()@{\code{dof\_matrix\_sub\_chain()}}}%
%%
\item[Synopsis]~\hfill

\begin{lstlisting}
sub_chain = bas_fcts_sub_chain(scratch_mem, master_chain, which);
sub_chain = fe_space_sub_chain(scratch_mem, master_chain, which);
sub_chain = dof_real_vec_sub_chain(scratch_mem, master_chain, which);
sub_chain = dof_real_vec_d_sub_chain(scratch_mem, master_chain, which);
sub_chain = dof_real_d_vec_sub_chain(scratch_mem, master_chain, which);
sub_chain = dof_dof_vec_sub_chain(scratch_mem, master_chain, which);
sub_chain = dof_int_vec_sub_chain(scratch_mem, master_chain, which);
sub_chain = dof_uchar_vec_sub_chain(scratch_mem, master_chain, which);
sub_chain = dof_schar_vec_sub_chain(scratch_mem, master_chain, which);
sub_chain = dof_ptr_vec_sub_chain(scratch_mem, master_chain, which);
sub_matrix =
  dof_matrix_sub_chain(scratch_mem, matrix, row_which, col_which)
\end{lstlisting}
\item[Description]~\hfill

  Form a sub-chain of the specified ``master''-chain, using the number
  of bits set in \code{which} to select the components to copy.
  Sub-chains are chains consisting of shallow copies of the members of
  the master-chain, which share the underlying coefficient data which
  the members of the master chain. A sub-chain is up-to-date after
  generating it, however, if the size of the master objects changed,
  prominently because of mesh adaptation, the corresponding update
  routine has to be called to update the sub-chain accordingly, see
  below. Note that for DOF-vectors and -matrices the
  structure-component \code{unchained} of the sub-chain objects will
  point to the original objects. Note also that this does \emph{not}
  hold for sub-chains of \code{BAS\_FCTS} and \code{FE\_SPACE}
  objects: here the component \code{unchained} will always point to an
  instance of those objects which is not concatenated which any other
  object, i.e. is indeed an unchained copy.

  Note that the sub-chain will be destroyed when the scratch-memory
  handle \code{scratch\_mem} is deleted by calling
  \code{SCRATCH\_MEM\_ZAP(scratch\_mem)}.
\item[Arguments]~\hfill
  \begin{descr}
    \kitem{scratch\_mem} A pointer to a scratch-memory area, see
    \secref{S:scratch_memory}.
    %%
    \kitem{master\_chain} The master-chain.
    %%
    \kitem{which} A bit mask which determines which parts of
    \code{master\_chain} take part in forming the sub-chain: if bit
    $n$ is set in the \code{which}-mask, then component number $n$ of
    the master-chain will make its way into the sub-chain.
  \end{descr}
\item[Return Value]~\hfill

A pointer to the first element of the sub-chain.  
\end{description}

\hrulefill

\begin{description}
\fdx{update_dof_real_vec_sub_chain()@{\code{update\_dof\_real\_vec\_sub\_chain()}}}%
\fdx{update_dof_real_d_vec_sub_chain()@{\code{update\_dof\_real\_d\_vec\_sub\_chain()}}}%
\fdx{update_dof_real_vec_d_sub_chain()@{\code{update\_dof\_real\_vec\_d\_sub\_chain()}}}%
\fdx{update_dof_dof_vec_sub_chain()@{\code{update\_dof\_dof\_vec\_sub\_chain()}}}%
\fdx{update_dof_int_vec_sub_chain()@{\code{update\_dof\_int\_vec\_sub\_chain()}}}%
\fdx{update_dof_uchar_vec_sub_chain()@{\code{update\_dof\_uchar\_vec\_sub\_chain()}}}%
\fdx{update_dof_schar_vec_sub_chain()@{\code{update\_dof\_schar\_vec\_sub\_chain()}}}%
\fdx{update_dof_ptr_vec_sub_chain()@{\code{update\_dof\_ptr\_vec\_sub\_chain()}}}%
%%
\fdx{update_dof_matrix_sub_chain()@{\code{update\_dof\_matrix\_sub\_chain()}}}%
\fdx{update_bas_fcts_sub_chain()@{\code{update\_bas\_fcts\_sub\_chain()}}}%
\fdx{update_fe_space_sub_chain()@{\code{update\_fe\_space\_sub\_chain()}}}%
\item[Synopsis]~\hfill

\begin{lstlisting}
update_dof_real_vec_sub_chain(sub_chain);
update_dof_real_d_vec_sub_chain(sub_chain);
update_dof_real_vec_d_sub_chain(sub_chain);
update_dof_dof_vec_sub_chain(sub_chain);
update_dof_int_vec_sub_chain(sub_chain);
update_dof_uchar_vec_sub_chain(sub_chain);
update_dof_schar_vec_sub_chain(sub_chain);
update_dof_ptr_vec_sub_chain(sub_chain);
update_dof_matrix_sub_chain(sub_chain);
\end{lstlisting}
\item[Description]~\hfill

  Update a sub-chain after mesh-adaptation. Note that there are no
  ``updaters'' for sub-chains of \code{BAS\_FCTS} and \code{FE\_SPACE}
  objects, simply because the sub-chains need not be updated in this
  case.
 
  Otherwise, the application must call
  \code{update\_XXX\_sub\_chain()} after adapting the mesh. Otherwise
  the meta-data stored in the elements forming the sub-chain will be
  inconsistent with the state of the mesh.
\item[Arguments]~\hfill
  \begin{descr}
    \kitem{sub\_chain} The head of the sub-chain. The master chain is
    not needed, because it can be accessed via
    \code{sub\_chain->unchained}.
  \end{descr}
\end{description}

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