.. UFC documentation

.. _ufc_introduction:

#################
UFC documentation
#################

============
Introduction
============

Large parts of a finite element program are similar from problem to
problem and can therefore be coded as a general, reusable library.
Mesh data structures, linear algebra and finite element assembly are
examples of operations that are naturally coded in a
problem-independent way and made available in reusable
libraries~\cite{www:fenics,www:petsc,www:sundance,www:deal.II,www:trilinos,www:diffpack}.
However, some parts of a finite element program are difficult to code
in a problem-independent way. In particular, this includes the
evaluation of the \emph{element tensor} (the `element stiffness
matrix'), that is, the evaluation of the local contribution from a
finite element to a global sparse tensor (the ``stiffness matrix'')
representing a discretized differential operator. These parts must
thus be implemented by the application programmer for each specific
combination of differential equation and discretization (finite
element spaces).

\index{form compilers} \index{FFC} \index{SyFi} However,
domain-specific compilers such as
FFC~\cite{www:ffc,logg:article:07,logg:article:09,logg:article:10,logg:article:11}
and SyFi~\cite{www:syfi} make it possible to automatically generate
the code for the evaluation of the element tensor. These \emph{form
compilers} accept as input a high-level description of a finite
element variational form and generate low-level code code for
efficient evaluation of the element tensor and associated quantities.
It thus becomes important to specify the \emph{interface} between form
compilers and finite element assemblers such that the code generated
by FFC, SyFi and other form compilers can be used to assemble finite
element matrices and vectors (and in general tensors).


Unified Form-assembly Code
==========================

UFC (Unified Form-assembly Code) is a unified framework for finite
element assembly. More precisely, it defines a fixed interface for
communicating low level routines (functions) for evaluating and
assembling finite element variational forms. The UFC interface
consists of a single header file \texttt{ufc.h} that specifies a C++
interface that must be implemented by code that complies with the UFC
specification.

Both FFC (since version 0.4.0) and SyFi (since version 0.3.4)
generate code that complies with the UFC specification. Thus, code
generated by FFC and SyFi may be used interchangeably by any UFC-based
finite element assembler, such as DOLFIN~\cite{www:dolfin}.


Aim and scope
=============

The UFC interface has been designed to make a minimal amount of
assumptions on the form compilers generating the UFC code and the
assemblers built on top of the UFC specification. Thus, the UFC
specification provides a minimal amount of abstractions and data
structures. Programmers wishing to implement the UFC specification
will typically want to create system-specific (but simple) wrappers
for the generated code.

Few assumptions have also been made on the underlying finite element
methodology. The current specification is limited to affinely mapped
cells, but does not restrict the mapping of finite element function
spaces. Thus, UFC code may be generated for elements where basis
functions are transformed from the reference cell by the affine
mapping, as well as for elements where the basis functions must be
transformed by the Piola mapping. UFC code has been successfully
generated and used in finite element codes for standard continuous
Galerkin methods (Lagrange finite elements of arbitrary order),
discontinuous Galerkin methods (including integrals of jumps and
averages over interior facets) and mixed methods (including
Brezzi--Douglas--Marini and Raviart--Thomas elements).

Outline
=======

In the next section, we give an overview of finite element assembly
and explain how the code generated by form compilers may be used as
the basic building blocks in the assembly algorithm. We then present
the UFC interface in detail in Section~\ref{sec:interface}. In
Section~\ref{sec:referencecells} and Section~\ref{sec:numbering}, we
define the reference cells and numbering conventions that must be
followed by UFC-based form compilers and assemblers.



=======================
Finite element assembly
=======================

In this section, we present a general algorithm for assembly of finite
element variational forms and define the concepts that the UFC interface
is based on.

