\chapter{Interface specification}
\label{sec:interface}
\index{interface}

\section{A short remark on design}
\index{design}

UFC is organized as a minimalistic set of abstract C++ classes
representing low-level abstractions of the finite element method. The
functions in these classes are mainly of two types: (i) functions
returning dimensions, which are typically used to allocate an array,
and (ii) functions that fill an array with values.

It is considered the assembly routine's responsibility
to allocate and deallocate arrays of proper size.
Consider for example the function for evaluating the $i$th basis
function in the class \texttt{ufc::finite\_element}:
\begin{code}
virtual void evaluate_basis(unsigned int i,
                            double* values,
                            const double* coordinates,
                            const cell& c) const = 0;
\end{code}
This function assumes that the array \texttt{values} has the correct
size, which may be obtained by calling the functions
\texttt{value\_rank} and \texttt{value\_dimension} as described in
detail below.

Thus, the UFC interface is a low-level interface that should be simple
to integrate into an existing C++ finite element code, but which is
probably not suitable to be exposed as part of an end-user interface.

The UFC interface is defined by a single header file \texttt{ufc.h}
which defines the central interface class \texttt{ufc::form} and a
small set of auxiliary interface classes. In addition, a pair of data
structures \texttt{ufc::mesh} and \texttt{ufc::cell} are defined and
used for passing data to the interface functions. All functions
defined by the UFC interface are \emph{pure virtual}, meaning that all
these functions must be overloaded in each implementation of the
classes.  All but two functions (\texttt{init\_mesh} and
\texttt{init\_cell}) are \texttt{const}, meaning that calling these
\texttt{const} functions will leave the UFC objects unchanged.  Input
argument (pointers) are always \texttt{const}, while output arguments
(pointers) are always non-\texttt{const}.  \index{ufc.h}

The interface is presented below in the same order as it is defined in
the header file \texttt{ufc.h}. Thus, the interface is presented
bottom-up, starting with the definition of basic data structures and
ending with the definition of the main \texttt{ufc::form} interface
class.

\section{Cell shapes}
\index{Cell shapes}
\index{\texttt{interval}}
\index{\texttt{triangle}}
\index{\texttt{quadrilateral}}
\index{\texttt{tetrahedron}}
\index{\texttt{hexahedron}}

\begin{code}
enum shape {interval,
            triangle,
            quadrilateral,
            tetrahedron,
            hexahedron};
\end{code}

This enumeration includes all cell shapes that are covered by the UFC
specification, see Chapter~\ref{sec:referencecells}.

\section{The class \texttt{ufc::mesh}}
\index{\texttt{ufc::mesh}}

The class \texttt{ufc::mesh} defines a data structure containing basic
information about an unstructured mesh. It is used for passing a
minimal amount of information about the global mesh to UFC functions.

\subsection{The integer \texttt{topological\_dimension}}

\begin{code}
unsigned int topological_dimension;
\end{code}

The unsigned integer \texttt{topological\_dimension} holds the
topological dimension of the mesh, that is, the topological dimension
of the cells of the mesh. For the supported cell shapes defined above,
the topological dimensions are as follows: \texttt{interval} has
dimension one, \texttt{triangle} and \texttt{quadri\-lateral} have
dimension two, and \texttt{tetrahedron} and \texttt{hexahedron} have
dimension three.

\subsection{The integer \texttt{geometric\_dimension}}

\begin{code}
unsigned int geometric_dimension;
\end{code}

The unsigned integer \texttt{geometric\_dimension} holds the geometric
dimension of the mesh, that is, the dimension of the coordinates of
the mesh vertices.  Often, the geometric dimension is equal to the
topological dimension, but they may differ. For example, one may have
a topologically two-dimensional mesh embedded in three-dimensional
space.

\subsection{The array \texttt{num\_entities}}

\begin{code}
unsigned int* num_entities;
\end{code}

The array \texttt{num\_entities} should contain the number of entities
within each topological dimension of the mesh (see
Chapter~\ref{sec:referencecells}). The size of the array should be
equal to the topological dimension of the mesh plus one.

Thus, for a mesh of tetrahedral cells, \texttt{num\_entities[0]}
should contain the number of vertices, \texttt{num\_entities[1]}
should contain the number of edges (if they are needed, see
\texttt{ufc::dofmap::needs\_mesh\_entities} below),
\texttt{num\_en\-tities[2]} should contain the number of faces, and
\texttt{num\_entities[3]} should contain the number of volumes.  If
\texttt{d} is the topological dimension of the mesh,
\texttt{num\_entities[d]} should contain the number of cells or
elements.

\section{The class \texttt{ufc::cell}}
\index{\texttt{ufc::cell}}

The class \texttt{ufc::cell} defines the data structure for a cell in
a mesh. Its intended use is not as a building block in a mesh data
structure, but merely as a view of specific data for a single cell.
It is used to pass cell data to UFC functions with a minimal amount of
assumptions on how the computational mesh is represented and stored.

\subsection{The enum variable \texttt{cell\_shape}}

\begin{code}
shape cell_shape;
\end{code}

The variable \texttt{cell\_shape} should be set to the corresponding
\texttt{ufc::shape} for the cell.

\subsection{The integer \texttt{topological\_dimension}}

\begin{code}
unsigned int topological_dimension;
\end{code}

The integer \texttt{topological\_dimension} should be set to the
topological dimension of the cell (see \texttt{ufc::mesh} above).

\subsection{The integer \texttt{geometric\_dimension}}

\begin{code}
unsigned int geometric_dimension;
\end{code}

The integer \texttt{geometric\_dimension} should be set to the
geometric dimension of the cell (see \texttt{ufc::mesh} above).

\subsection{The array \texttt{entity\_indices}}

\begin{code}
unsigned int** entity_indices;
\end{code}

The array \texttt{entity\_indices} should contain the global indices
for all entities of the cell (see Chapter~\ref{sec:referencecells}).
The length of the array \texttt{entity\_indices} should be equal to
the value of the variable \texttt{topological\_dimension} plus one.

Thus, \texttt{entity\_indices[0]} should be an array containing the
global indices of all the vertices of the cell,
\texttt{entity\_indices[1]} should be an array containing the global
indices of all the edges of the cell, etc. The sizes of these arrays
are implicitly defined by the cell type.

Note that the entity indices are not always needed for all entities of
the cell. Which entities are required is specified by the
\texttt{ufc::dofmap} class (see
\texttt{ufc::dofmap::needs\_mesh\_entities} below).

\subsection{The array \texttt{coordinates}}

\begin{code}
double** coordinates;
\end{code}

The array \texttt{coordinates} should contain the global coordinates
for all vertices of the cell and thus its length should be equal to
number of vertices of the cell. The length of the array
\texttt{coordinates[0]} should be equal to the value of the variable
\texttt{geometric\_dimension} and it should contain the $x$, $y$,
\ldots coordinates of the first vertex etc.

\subsection{The integer \texttt{index}}
Introduced in UFC version 2.0.

\begin{code}
unsigned int index;
\end{code}

The integer \texttt{index} should contain the global index for the
cell. This is a short-cut for
\texttt{entity\_indices[topological\_dimension][0]}.

\subsection{The integer \texttt{local\_facet}}
Introduced in UFC version 2.0.

\begin{code}
int local_facet;
\end{code}

The integer \texttt{local\_facet} can be used during callbacks to the
\texttt{evaluate} function of \texttt{ufc::function} to specify the
local index of a facet (relative to the cell) on which the function is
being evaluated. In all other cases, this variable should be set to
\texttt{-1}.

\subsection{The integer \texttt{mesh\_identifier}}
Introduced in UFC version 2.0.

\begin{code}
int mesh_identifier;
\end{code}

The integer \texttt{mesh\_identifier} can be used during callbacks to
the \texttt{evaluate} function of \texttt{ufc::function} to specify a
global identifier for the mesh on which the function is being
evaluated. This allows \texttt{ufc::function} subclasses to handle
evaluation differently on different meshes. If not used, this variable
should be set to \texttt{-1}.

\section{The class \texttt{ufc::function}}
\index{\texttt{ufc::function}}

The class \texttt{ufc::function} is an interface for evaluation of
general tensor-valued functions on the cells of a mesh.

\subsection{The function \texttt{evaluate}}

\begin{code}
virtual void evaluate(double* values,
                      const double* coordinates,
                      const cell& c) const = 0;
\end{code}

The only function in this class is \texttt{evaluate}, which evaluates
all the value components of the function at a given point in a given
cell of the mesh.

The output of \texttt{evaluate} should be written to the array
\texttt{values}. For a scalar-valued function, a single value should be
written to \texttt{values[0]}. For general tensor-valued functions,
the values should be written in a flattened row-major ordering of the
tensor values. Thus, for a function $f : K \rightarrow \R^{2x2}$ (where $A =
f(x)$ is a $2 \times 2$ matrix), the array \texttt{values} should contain
the values $A_{11}, A_{12}, A_{21}, A_{22}$ in this order.

The input to \texttt{evaluate} are the coordinates of a point in a cell
and the UFC view of the cell containing that point.

See also the description of
\texttt{ufc::finite\_element::evaluate\_dof} below.

\section{The class \texttt{ufc::finite\_element}}
\index{\texttt{ufc::finite\_element}}

The class \texttt{ufc::finite\_element} represents a finite element in
the classical Ciarlet sense~\cite{Cia78}, or rather a particular
instance of a finite element for a particular choice of nodal basis
functions. Thus, a \texttt{ufc::finite\_element} has functions for
accessing the shape of the finite element, the dimension of the
polynomial function space, the basis functions of the function space
(and their derivatives), and the linear functionals defining the
degrees of freedom. In addition, a \texttt{ufc::finite\_element}
provides functionality for interpolation.

\subsection{The function \texttt{signature}}

\begin{code}
virtual const char* signature() const = 0;
\end{code}

This function returns a signature string that uniquely identifies the
finite element. This can be used to compare whether or not two given
\texttt{ufc::fi\-nite\_element} objects are identical.

\subsection{The function \texttt{cell\_shape}}

\begin{code}
virtual shape cell_shape() const = 0;
\end{code}

This function returns the shape of the cell the finite element is
defined on.

\subsection{The function \texttt{topological\_dimension}}
Introduced in UFC version 2.0.

\begin{code}
virtual unsigned int topological_dimension() const = 0;
\end{code}

This function returns the topological dimension of the cell the finite
element is defined on.

\subsection{The function \texttt{geometric\_dimension}}
Introduced in UFC version 2.0.

\begin{code}
virtual unsigned int geometric_dimension() const = 0;
\end{code}

This function returns the geometric dimension of the cell the finite
element is defined on.

\subsection{The function \texttt{space\_dimension}}

\begin{code}
virtual unsigned int space_dimension() const = 0;
\end{code}

This function returns the dimension of the local finite element space
($|V_h^K|$), which is equal to the number of basis functions. This
should also be equal to the value of \texttt{local\_dimension()} for
the corresponding \texttt{ufc::dofmap} (see below).

\subsection{The function \texttt{value\_rank}}

\begin{code}
virtual unsigned int value_rank() const = 0;
\end{code}

A finite element can have general tensor-valued basis functions.  The
function \texttt{value\_rank} returns the rank of the value space of
the basis functions. For a scalar element, this function should return
zero, for vector-valued functions it should return one, for
matrix-valued functions it should return two, etc. For mixed elements, this
may not always make sense, for example with a tensor-vector-scalar element.
Thus the value rank of a mixed element must be 1 if any of the subelements have
different value ranks.

\subsection{The function \texttt{value\_dimension}}

\begin{code}
virtual unsigned int
value_dimension(unsigned int i) const = 0;
\end{code}

This function returns the dimension of the value space of the finite
element basis functions for the given axis, where the given axis must
be a number between zero and the value rank minus one.

Note that the total size (number of values) of the value space is
obtained as the product of \texttt{value\_dimension(i)} for $0 \le i <$
\texttt{value\_rank()}. For a mixed element with value rank 1
Since the value rank of a mixed element must be 1 if any of the subelements
have different value ranks, \texttt{value\_dimension(0)} is then the total value
size of all the subelements.

\subsection{The function \texttt{evaluate\_basis}}

\begin{code}
virtual void evaluate_basis(unsigned int i,
                            double* values,
                            const double* coordinates,
                            const cell& c) const = 0;
\end{code}

This function evaluates basis function \texttt{i} at the given
\texttt{coordinates} within the given cell \texttt{c}, and stores the
values in the array \texttt{values}. The size of the output array
should be equal to size of the value space (see
\texttt{value\_dimension} above).

The point defined by \texttt{coordinates} should be located inside the
cell~\texttt{c}. If the point is located outside the cell, then the
result is undefined.~\footnote{In particular, the basis functions
  generated by FIAT/FFC are undefined along the line $y = 1$ on the
  UFC reference element since the collapsed cube mapping used by FIAT
  is singular along that line.}

\subsection{The function \texttt{evaluate\_basis\_all}}
Introduced in UFC version 1.1.

\begin{code}
virtual void evaluate_basis_all(double* values,
                                const double* coordinates,
                                const cell& c) const = 0;
\end{code}

As \texttt{evaluate\_basis}, but evaluates all basis functions at
once, which can be implemented much more effectively than multiple
calls to \texttt{evaluate\_basis}. The size of the output array
should be equal to size of the value space times the number of
basis functions. The computed values for a single basis function
are placed contiguously in the array.

Note that just as for \texttt{evaluate\_basis}, the point defined by
\texttt{coordinates} should be located inside the cell~\texttt{c}. The
result is otherwise undefined.

\subsection{The function \texttt{evaluate\_basis\_derivatives}}

\begin{code}
virtual void
evaluate_basis_derivatives(unsigned int i,
                           unsigned int n,
                           double* values,
                           const double* coordinates,
                           const cell& c) const = 0;
\end{code}

This function evaluates all order \texttt{n} derivatives of basis
function \texttt{i} at the given \texttt{coordinates} within the given
\texttt{cell}, and stores the values in the array \texttt{values}.
Derivatives may be obtained up to the polynomial degree of the finite
element function space with higher degree derivatives evaluating to
zero.

The number of derivatives is given by $d^n$ where $d$ is the geometric
dimension of the cell. For $n = 1$, $d = 3$, the order of the
derivatives is naturally $\partial/\partial x$, $\partial/\partial y$,
$\partial/\partial z$. For $n = 2$, $d = 3$, the order of the
derivatives is $\frac{\partial^2}{\partial x\partial x},
\frac{\partial^2}{\partial x\partial y}, \ldots,
\frac{\partial^2}{\partial z\partial z}$. Thus, the derivatives are
stored in a flattened row-major ordering based on the derivative
spatial dimensions.

For tensor-valued basis functions, the ordering of derivatives is
row-major based on the value space dimensions followed by the
derivative spatial dimensions.

Note that just as for \texttt{evaluate\_basis}, the point defined by
\texttt{coordinates} should be located inside the cell~\texttt{c}. The
result is otherwise undefined.

\subsection{The function \texttt{evaluate\_basis\_derivatives\_all}}
Introduced in UFC version 1.1.

\begin{code}
virtual void
evaluate_basis_derivatives_all(unsigned int n,
                               double* values,
                               const double* coordinates,
                               const cell& c) const = 0;
\end{code}

As \texttt{evaluate\_basis\_derivatives}, but evaluated for all
basis functions at once, which can be implemented much more
effectively than multiple calls to \texttt{evaluate\_basis\_derivatives}.
The size of the output array should be equal to the corresponding size
defined for \texttt{evaluate\_basis\_derivatives} times the number of
basis functions. The computed values for a single basis function
are placed contiguously in the array.

Note that just as for \texttt{evaluate\_basis}, the point defined by
\texttt{coordinates} should be located inside the cell~\texttt{c}. The
result is otherwise undefined.

\subsection{The function \texttt{evaluate\_dof}}

\begin{code}
virtual double evaluate_dof(unsigned int i,
                            const function& f,
                            const cell& c) const = 0;
\end{code}

This function evaluates and returns the value of the degree of freedom
\texttt{i} (which is a linear functional) on the given function
\texttt{f}.

For example, the degrees of freedom for Lagrange finite elements are
given by evaluation of \texttt{f} at a set of points. Other examples
of degrees of freedom include weighted integrals over facets or normal
components on facets.

\subsection{The function \texttt{evaluate\_dofs}}
Introduced in UFC version 1.1.

\begin{code}
virtual void evaluate_dofs(double* values,
                           const function& f,
                           const cell& c) const = 0;
\end{code}

Vectorized version of \texttt{evaluate\_dof} for efficiency,
returning the values of all degrees of freedom in the array \texttt{values}.

\subsection{The function \texttt{interpolate\_vertex\_values}}

\begin{code}
virtual void
interpolate_vertex_values(double* vertex_values,
                          const double* dof_values,
                          const cell& c) const = 0;
\end{code}

This function takes as input the array \texttt{dof\_values} containing
the expansion coefficients for some function in the nodal basis and
computes the values of that function at the vertices of the given
cell, storing those values in the array \texttt{vertex\_values}. If
the function is tensor-valued, the values are stored in the array
\texttt{vertex\_values} row-major on the list of vertices followed by the
row-major ordering of the tensor values as described above.

\subsection{The function \texttt{map\_from\_reference\_cell}}
Introduced in UFC version 2.0.

\begin{code}
virtual void map_from_reference_cell(double* x,
                                     const double* xhat,
                                     const cell& c) = 0;
\end{code}

This function maps a given coordinate \texttt{xhat} on the reference
cell to a coordinate \texttt{x} on a given \texttt{ufc::cell}.

\subsection{The function \texttt{map\_to\_reference\_cell}}
Introduced in UFC version 2.0.

\begin{code}
virtual void map_to_reference_cell(double* xhat,
                                   const double* x,
                                   const cell& c) = 0;
\end{code}

This function maps a given coordinate \texttt{x} on a given
\texttt{ufc::cell} to a coordinate \texttt{xhat} on the reference
cell.

\subsection{The function \texttt{num\_sub\_elements}}

\begin{code}
virtual unsigned int num_sub_elements() const = 0;
\end{code}

This function returns the number of subelements for a nested (mixed)
element. For simple elements (non-nested), this function should return
one.

A nested element is an element that is defined from a set of elements
by taking the direct sum (tensor product) of the polynomial spaces of
those elements. For example, the basis functions $\psi_1, \psi_2,
\ldots, \psi_m$ of a vector-valued Lagrange element may be constructed
from a scalar Lagrange element by repeating the basis functions
$\phi_1, \phi_2, \ldots, \phi_n$ of the scalar element and padding
with zeros: $\psi_1 = (\phi_1, 0), \psi_2 = (\phi_2, 0), \ldots,
\psi_n = (\phi_n, 0), \psi_{n+1} = (0, \phi_1), \psi_{n+2} = (0,
\phi_2), \ldots$.

Finite elements may be nested at arbitrary depth. For example, a mixed
Taylor--Hood element may be created by combining a vector-valued
quadratic Lagrange finite element with a scalar linear Lagrange finite
element, and the vector-valued element may in turn be created by
combining a set of scalar quadratic Lagrange elements.

\subsection{The function \texttt{create\_sub\_element}}

\begin{code}
virtual finite_element*
create_sub_element(unsigned int i) const = 0;
\end{code}

This factory function constructs a \texttt{ufc::finite\_element}
object for subelement \texttt{i}. The argument \texttt{i} must be an
integer between zero and the number of subelements
(\texttt{num\_sub\_elements}) minus one. If the element is simple
(non-nested), this function returns a zero pointer. The caller is
responsible for deleting the returned object.

Note that in earlier versions of UFC, this function returned a copy of
the element itself in the case of a simple element. To create a copy
of the element, use the \texttt{create} function instead.

\subsection{The function \texttt{create}}
Introduced in UFC version 2.0.

\begin{code}
virtual finite_element* create() const = 0;
\end{code}

This factory function creates a new instance of the generated
\texttt{ufc::finite\_\-element} subclass.

\section{The class \texttt{ufc::dofmap}}
\index{\texttt{ufc::dofmap}}

This class represents the local-to-global mapping of degrees of
freedom (dofs), or rather one particular instance of such a mapping
(there are many possible local-to-global mappings) as defined in
Equation \eqref{eq:iota_K}. The most central function of this class is
\texttt{tabulate\_dofs}, which tabulates the local-to-global mapping
from the degree of freedom indices on a local cell to a global vector of
degree of freedom indices.

\subsection{The function \texttt{signature}}

\begin{code}
virtual const char* signature() const = 0;
\end{code}

This function returns a signature string that uniquely identifies the
dofmap. This can be used to compare whether or not two given
\texttt{ufc::dofmap} objects are identical. (This may be used to
optimize the assembly of forms by caching previously computed
dofmaps.)

\subsection{The function \texttt{needs\_mesh\_entities}}

\begin{code}
virtual bool needs_mesh_entities(unsigned int d) const = 0;
\end{code}

This function returns true if the \texttt{ufc::dofmap} requires mesh
entities of topological dimension \texttt{d} to be available in
\texttt{ufc::cell} arguments. Thus, if this function returns false for
a given value of \texttt{d}, then the array
\texttt{entity\_indices[d]} of the \texttt{ufc::cell} data structure
will not be used during calls to \texttt{ufc::dofmap} functions. In
those cases, the array \texttt{entity\_indices[d]} may be set to zero.

This may be used to check which entities must be generated to tabulate
the local-to-global mapping. For example, linear Lagrange elements
will only need to know the vertices of each cell in the mesh, while
quadratic Lagrange elements will also need to know the edges of each
cell in the mesh.

\subsection{The function \texttt{init\_mesh}}

\begin{code}
virtual bool init_mesh(const mesh& mesh) = 0;
\end{code}

This function initializes the dofmap for a given mesh. If it returns
true, calls to \texttt{init\_cell} and \texttt{init\_cell\_finalize}
are required to complete the initialization. The function
\texttt{global\_dimension} be may only be called when the
initialization is complete.

\subsection{The function \texttt{init\_cell}}

\begin{code}
virtual void init_cell(const mesh& m,
                       const cell& c) = 0;
\end{code}

For \texttt{ufc::dofmap} objects where \texttt{init\_mesh} returns true,
this function must be called for each cell in the mesh to initialize
the dofmap.

\subsection{The function \texttt{init\_cell\_finalize}}

\begin{code}
virtual void init_cell_finalize() = 0;
\end{code}

For \texttt{ufc::dofmap} objects where \texttt{init\_mesh} returns
true, this function must be called after \texttt{init\_cell} is called
for each cell in the mesh to complete initialization of the dofmap.

\subsection{The function \texttt{topological\_dimension}}
Introduced in UFC version 1.1.

\begin{code}
virtual unsigned int topological_dimension() const = 0;
\end{code}

This function returns the topological dimension of the associated cell
shape.

\subsection{The function \texttt{geometric\_dimension}}
Introduced in UFC version 2.0.

\begin{code}
virtual unsigned int geometric_dimension() const = 0;
\end{code}

This function returns the geometric dimension of the associated cell
shape.

\subsection{The function \texttt{global\_dimension}}

\begin{code}
virtual unsigned int global_dimension() const = 0;
\end{code}

This function returns the dimension of the global finite element space
on the mesh that the \texttt{ufc::dofmap} has been initialized
for. The result of calling this function before the initialization is
complete is undefined.

\subsection{The function \texttt{local\_dimension}}
Changed in version 1.2.

\begin{code}
virtual unsigned int local_dimension(const cell& c) const = 0;
\end{code}

This function returns the dimension of the local finite element space
on a given cell.

\subsection{The function \texttt{max\_local\_dimension}}
Introduced in UFC version 1.2.

\begin{code}
virtual unsigned int max_local_dimension() const = 0;
\end{code}

This function returns the maximum dimension of the local finite element space
on a single cell.

\subsection{The function \texttt{num\_facet\_dofs}}

\begin{code}
virtual unsigned int num_facet_dofs() const = 0;
\end{code}

This function returns the number of dofs associated with a single facet
of a cell, including all dofs associated with mesh entities of lower
dimension incident with the facet. For example on a tetrahedron this
will include dofs associated with edges and vertices of the triangle face.
This is also the number of dofs that should be set if a Dirichlet
boundary condition is applied to a single facet.

\subsection{The function \texttt{num\_entity\_dofs}}
Introduced in UFC version 1.1.

\begin{code}
virtual unsigned int num_entity_dofs(unsigned int d) const = 0;
\end{code}

This function returns the number of dofs associated with a single
mesh entity of dimension \texttt{d} in a cell, not including
dofs associated with incident entities of lower dimension
(unlike \texttt{num\_facet\_dofs()}).
It is assumed that all cells of the mesh have the same number
of degrees of freedom on each mesh entity of the same dimension.

\subsection{The function \texttt{tabulate\_dofs}}

\begin{code}
virtual void tabulate_dofs(unsigned int* dofs,
                           const mesh& m,
                           const cell& c) const = 0;
\end{code}

This function tabulates the global dof indices corresponding to each
dof on the given cell. The size of the output array \texttt{dofs}
should be equal to the value returned by \texttt{local\_dimension()}.

\subsection{The function \texttt{tabulate\_facet\_dofs}}

\begin{code}
virtual void
tabulate_facet_dofs(unsigned int* dofs,
                    unsigned int facet) const = 0;
\end{code}

This function tabulates the local dof indices associated with a given local
facet, including all dofs associated with mesh entities of lower dimension
incident with the facet. The size of the output array \texttt{dofs} should
equal the value returned by \texttt{num\_facet\_dofs}.

\subsection{The function \texttt{tabulate\_entity\_dofs}}
Introduced in UFC version 1.1.

\begin{code}
virtual void tabulate_entity_dofs(unsigned int* dofs,
                                  unsigned int d,
                                  unsigned int i) const = 0;
\end{code}

This function tabulates the local dof indices associated with a given local
mesh entity \texttt{i} of dimension \texttt{d}, i.e. mesh entity (d, i),
not including dofs associated with incident entities of lower dimension
(unlike \texttt{tabulate\_facet\_dofs}).
The size of the output array \texttt{dofs} should equal
the value returned by the function \texttt{num\_entity\_dofs(d)}.

As an example, calling \texttt{tabulate\_entity\_dofs} for a face (d = 2)
should yield only the dofs associated with the face that are not associated
with vertices and edges. Thus \texttt{tabulate\_entity\_dofs} can
be used to build connectivity information.


\subsection{The function \texttt{tabulate\_coordinates}}

\begin{code}
virtual void tabulate_coordinates(double** coordinates,
                                  const cell& c) const = 0;
\end{code}

This function tabulates the coordinates for each dof on the given
cell. For Lagrange elements, this function will tabulate a set of
points on the given cell such that the dofs of the finite element are
given by evaluation at those points.

For elements that do not have a direct relationship between
coordinates and dofs, an attempt should be made at a sensible
implementation of this function. For example, if a dof is defined as
the integral over a facet, the midpoint of the facet can be used. If
no other choice makes sense, the midpoint of the cell can be used as a
last resort. This function must thus be used with care if
non-Lagrangian elements are used.

The size of the output array \texttt{coordinates} should be equal to
the value returned by \texttt{local\_dimension()} and the size of each
subarray \texttt{coordi\-nates[0]}, \texttt{coordinates[1]} etc should
be equal to the geometric dimension of the mesh, which can be obtained
with the function \texttt{dofmap::geometric\_\-dimension()}.

\subsection{The function \texttt{num\_sub\_dofmaps}}

\begin{code}
virtual unsigned int num_sub_dofmaps() const = 0;
\end{code}

This function returns the number of sub-dofmaps for a nested (mixed)
element. For a discussion on the subelement concept, see the
documentation of the function
\texttt{ufc::finite\_element::num\_sub\_elements}. For simple
elements (non-nested), this function should return one.

\subsection{The function \texttt{create\_sub\_dofmap}}

\begin{code}
virtual dofmap* create_sub_dofmap(unsigned int i) const = 0;
\end{code}

This factory function constructs a \texttt{ufc::dofmap} object for
subelement \texttt{i}. The argument \texttt{i} must be a number
between zero and the number of sub-dofmaps
(\texttt{num\_sub\_dofmaps}) minus one. If the dofmap is simple
(non-nested), this function returns a zero pointer. The caller is
responsible for deleting the returned object.

Note that in earlier versions of UFC, this function returned a copy of
the dofmap itself in the case of a simple element. To create a copy
of the element, use the \texttt{create} function instead.

\subsection{The function \texttt{create}}
Introduced in UFC version 2.0.

\begin{code}
virtual dofmap* create() const = 0;
\end{code}

This factory function creates a new instance of the generated
\texttt{ufc::dofmap} subclass.

\section{The integral classes}

As described in Section~\ref{sec:assembly}, and in particular Equation
\eqref{eq:form_integrals}, the global sparse tensor
(the ``stiffness matrix'') representing a given form (differential
operator) may be assembled by summing the contributions from the local
cells, exterior facets and interior facets of the mesh.

These contributions are represented in the UFC interface by the
classes \texttt{cell\_integral}, \texttt{exterior\_facet\_integral}
and \texttt{interior\_facet\_integral}. Each of these three integral
classes has a single function \texttt{tabulate\_tensor} which may be
called to compute the corresponding local contribution (cell tensor,
exterior facet tensor or interior facet tensor).

\section{The class \texttt{ufc::cell\_integral}}
\index{\texttt{ufc::cell\_integral}}

The class \texttt{ufc::cell\_integral} represents the integral of a
form over a local cell in a finite element mesh. It has a single
function \texttt{tabulate\_tensor} which may be called to tabulate the
values of the cell tensor for a given cell.

\subsection{The function \texttt{tabulate\_tensor}}
\index{\texttt{tabulate\_tensor}}

\begin{code}
virtual void tabulate_tensor(double* A,
                             const double * const * w,
                             const cell& c) const = 0;
\end{code}

This function tabulates the values of the cell tensor for a form into
the given array \texttt{A}. The size of this array should be equal to
the product of the local space dimensions for the set of finite
element function spaces corresponding to the arguments of the
form. For example, when computing the matrix for a bilinear form
defined on piecewise linear scalar elements on triangles, the space dimension
of the local finite element is three and so the size of the array
\texttt{A} should be $3 \times 3 = 9$.

The array \texttt{w} should contain the expansion coefficients for all
\emph{coefficients} of the form in the finite element nodal basis for
each corresponding function space. Thus, the size of the array
\texttt{w} should be equal to the number of coefficients~$n$, and the
size of each each array \texttt{w[0]}, \texttt{w[1]} etc should be
equal to the space dimension of the corresponding local finite element
space.

\subsection{The function \texttt{tabulate\_tensor} (quadrature version)}
\index{\texttt{tabulate\_tensor} (quadrature version)}
Introduced in UFC version version 2.0

\begin{code}
virtual void
tabulate_tensor(double* A,
                const double * const * w,
                const cell& c,
                unsigned int num_quadrature_points,
                const double * const * quadrature_points,
                const double* quadrature_weights) const = 0;
\end{code}

This function is identical to \texttt{tabulate\_tensor} described
above but computes the integral over the cell using the given set of
quadrature points and weights. Note that the quadrature points should
be specified on the reference cell. By a careful choice of quadrature
points, this function can be used to integrate over subsets of cells.

\section{The class \texttt{ufc::exterior\_facet\_integral}}
\index{\texttt{ufc::exterior\_facet\_integral}}

The class \texttt{ufc::exterior\_facet\_integral} represents the
integral of a form over a local exterior facet (boundary facet) in a
finite element mesh. It has a single function
\texttt{tabulate\_tensor} which may be called to tabulate the values
of the exterior facet tensor for a given facet.

\subsection{The function \texttt{tabulate\_tensor}}
\index{\texttt{tabulate\_tensor}}

\begin{code}
virtual void tabulate_tensor(double* A,
                             const double * const * w,
                             const cell& c,
                             unsigned int facet) const = 0;
\end{code}

The arrays \texttt{A} and \texttt{w} have the same function and should
have the same sizes as described in the documentation for
\texttt{cell\_integral::tabulate\_tensor}. Thus, the values of the
exterior facet integral will be tabulated into the array \texttt{A}
and the nodal basis expansions of all coefficients should be provided
in the array \texttt{w}.

The additional argument \texttt{facet} should specify the local number
of the facet with respect to its (single) incident cell. Thus, when
the facet is an edge of a triangle, the argument \texttt{facet} should
be an integer between zero and two (0, 1, 2) and when the facet is a
facet of a tetrahedron, the argument \texttt{facet} should be an
integer between zero and three (0, 1, 2, 3).

\subsection{The function \texttt{tabulate\_tensor} (quadrature version)}
\index{\texttt{tabulate\_tensor} (quadrature version)}
Introduced in version version 2.0

\begin{code}
virtual void
tabulate_tensor(double* A,
                const double * const * w,
                const cell& c,
                unsigned int num_quadrature_points,
                const double * const * quadrature_points,
                const double* quadrature_weights) const = 0;
\end{code}

This function is identical to \texttt{tabulate\_tensor} described
above but computes the integral over the cell using the given set of
quadrature points and weights. Note that the quadrature points should
be specified on the reference cell. By a careful choice of quadrature
points, this function can be used to integrate over subsets of facets.

\section{The class \texttt{ufc::interior\_facet\_integral}}
\index{\texttt{ufc::interior\_facet\_integral}}

The class \texttt{ufc::interior\_facet\_integral} represents the
integral of a form over a local interior facet in a finite element
mesh. It has a single function \texttt{tabulate\_tensor} which may be
called to tabulate the values of the interior facet tensor for a given
facet.

\subsection{The function \texttt{tabulate\_tensor}}

\begin{code}
virtual void tabulate_tensor(double* A,
                             const double * const * w,
                             const cell& c0,
                             const cell& c1,
                             unsigned int facet0,
                             unsigned int facet1) const = 0;
\end{code}

Just as for the \texttt{cell\_integral} and
\texttt{exterior\_facet\_integral} classes, the
\texttt{tabulate\_tensor} function for the class
\texttt{interior\_facet\_integral} tabulates the values of the local
(interior facet) tensor into the array \texttt{A}, given the nodal
basis expansions of the form coefficients in the array \texttt{w}.
However, the interior facet tensor contains contributions from the two
incident cells of an interior facet and thus the dimensions of these
arrays are different.

On each interior facet, the two incident (neighboring) cells form a
``macro cell'' consisting of the total set of local basis functions on
the two cells. The set of basis functions on the macro element is
obtained by extending the basis functions on each of the two cells by
zero to the macro cell. Thus, the space dimension of the finite
element function space on the macro element is twice the size of the
finite element function space on a single cell. The ordering of basis
functions and degrees of freedom on the macro cell is obtained by
first enumerating the basis functions and degrees of freedom on one of
the two cells and then the basis functions and degrees of freedom on
the second cell.

Thus the size of the array \texttt{A} should be equal to the product
of twice the local space dimensions for the set of finite element
function spaces corresponding to the arguments of the form. For
example, when computing the matrix for a bilinear form defined on
piecewise linear elements on triangles, the space dimension of the
local finite element is three and so the size of the array \texttt{A}
should be $6 \times 6 = 36$.

Similarly, the array \texttt{w} should contain the expansion
coefficients for all \emph{coefficients} of the form in the finite
element nodal basis for each corresponding function space on the macro
cell. Thus, the size of the array \texttt{w} should be equal to the
number of coefficients~$n$ and the size of each each array
\texttt{w[0]}, \texttt{w[1]} etc should be equal to twice the space
dimension of the corresponding local finite element space.

The additional arguments \texttt{facet0} and \texttt{facet1} should
specify the local number of the facet with respect to its two incident
cells. Thus, when the facet is an edge of a triangle, each of these
arguments may be an integer between zero and two (0, 1, 2) and when
the facet is a face of a tetrahedron, each of these arguments may be
an integer between zero and three (0, 1, 2, 3).

\subsection{The function \texttt{tabulate\_tensor} (quadrature version)}
\index{\texttt{tabulate\_tensor} (quadrature version)}
Introduced in version version 2.0

\begin{code}
virtual void
tabulate_tensor(double* A,
                const double * const * w,
                const cell& c,
                unsigned int num_quadrature_points,
                const double * const * quadrature_points,
                const double* quadrature_weights) const = 0;
\end{code}

This function is identical to \texttt{tabulate\_tensor} described
above but computes the integral over the cell using the given set of
quadrature points and weights. Note that the quadrature points should
be specified on the reference cell. By a careful choice of quadrature
points, this function can be used to integrate over subsets of facets.

\section{The class \texttt{ufc::form}}
\index{\texttt{ufc::form}}

The \texttt{ufc::form} class is the central part of the UFC interface
and it represents a form
\begin{equation}
  a = a(v_1, \ldots, v_r; w_1, \ldots, w_n),
\end{equation}
defined on the product space $V_h^1 \times V_h^2 \times \cdots \times
V_h^r \times W_h^1 \times W_h^2 \times \cdots \times W_h^n$ of two
sets $\{V_h^j\}_{j=1}^r, \{W_h^j\}_{j=1}^n$ of finite element function
spaces on a triangulation $\mathcal{T}$ of a domain $\Omega \subset
\R^d$.

A \texttt{ufc::form} provides functions for accessing the rank~$r$ and
number of coefficients~$n$ for a form, and factory functions for
creating UFC objects for the corresponding cell integrals, exterior
facet integrals, interior facet integrals, and all associated finite
elements and dofmaps (local-to-global mappings).

\subsection{The function \texttt{signature}}

\begin{code}
virtual const char* signature() const = 0;
\end{code}

This function returns a signature string that uniquely identifies the
form. This can be used to compare whether or not two given
\texttt{ufc::form} objects are identical.

\subsection{The function \texttt{rank}}

\begin{code}
virtual unsigned int rank() const = 0;
\end{code}

This function returns the rank~$r$ of the global tensor generated by
the form (the arity of the form).

\subsection{The function \texttt{num\_coefficients}}

\begin{code}
virtual unsigned int num_coefficients() const = 0;
\end{code}

This function returns the number of coefficients~$n$ for the form.
Note that all integral terms of a form must have the same
coefficients, even if not all coefficients are present in each term of
the form.

\subsection{The function \texttt{num\_cell\_domains}}

\begin{code}
virtual unsigned int num_cell_domains() const = 0;
\end{code}

This function returns the number of different cell domains for the
form. A form may have an arbitrary number of integrals over disjoint
subdomains of the mesh.

\subsection{The function \texttt{num\_exterior\_facet\_domains}}

\begin{code}
virtual unsigned int num_exterior_facet_domains() const = 0;
\end{code}

This function returns the number of different exterior facet domains
for the form. A form may have an arbitrary number of integrals over
disjoint subdomains of the mesh boundary.

\subsection{The function \texttt{num\_interior\_facet\_domains}}

\begin{code}
virtual unsigned int num_interior_facet_domains() const = 0;
\end{code}

This function returns the number of different interior facet domains
for the form. A form may have an arbitrary number of integrals over
disjoint subsets of the interior facets of the mesh.

\subsection{The function \texttt{create\_finite\_element}}

\begin{code}
virtual finite_element*
create_finite_element(unsigned int i) const = 0;
\end{code}

This factory function constructs a \texttt{ufc::finite\_element}
object for form argument \texttt{i}. A form with rank~$r$ and number
of coefficients~$n$ has $r + n$ arguments, so this function returns
the finite element object for tensor axis $i$ if $i < r$, or the
finite element for coefficient $i - r$ if $i \geq r$.  The caller is
responsible for deleting the returned object.

\subsection{The function \texttt{create\_dofmap}}

\begin{code}
virtual dofmap*
create_dofmap(unsigned int i) const = 0;
\end{code}

This factory function constructs a \texttt{ufc::dofmap} object for
form argument \texttt{i}. A form with rank~$r$ and number of
coefficients~$n$ has $r + n$ arguments, so this function returns the
dofmap object for tensor axis $i$ if $i < r$, or the dofmap for
coefficient $i - r$ if $i \geq r$.  The caller is responsible for
deleting the returned object.

\subsection{The function \texttt{create\_cell\_integral}}

\begin{code}
virtual cell_integral*
create_cell_integral(unsigned int i) const = 0;
\end{code}

This factory function constructs a \texttt{cell\_integral} object for
cell domain \texttt{i}. The caller is responsible for deleting the
returned object.

If the integral evaluates to zero, this function may return a null
pointer.

\subsection{The function \texttt{create\_exterior\_facet\_integral}}

\begin{code}
virtual exterior_facet_integral*
create_exterior_facet_integral(unsigned int i) const = 0;
\end{code}

This factory function constructs an \texttt{exterior\_facet\_integral}
object for exterior facet domain \texttt{i}. The caller is responsible
for deleting the returned object.

If the integral evaluates to zero, this function may return a null
pointer.

\subsection{The function \texttt{create\_interior\_facet\_integral}}

\begin{code}
virtual interior_facet_integral*
create_interior_facet_integral(unsigned int i) const = 0;
\end{code}

This factory function constructs an \texttt{interior\_facet\_integral}
object for interior facet domain \texttt{i}. The caller is responsible
for deleting the returned object.

If the integral evaluates to zero, this function may return a null
pointer.
