formlanguage.tex

finite element library for mathematic majored research

\chapter{Form language}
\label{sec:formlanguage}
\index{form language}

\ffc{} uses a flexible and extensible language to define and process
multilinear forms. In this chapter, we discuss the details of this
form language. In the next section, we present a number of examples to
illustrate the use of the form language in applications.

%------------------------------------------------------------------------------
\section{Overview}

\ffc{} compiles a given multilinear form
\begin{equation}
  a : V_h^1 \times V_h^2 \times \cdots \times V_h^r \rightarrow \R
\end{equation}
into code that can be used to compute the corresponding tensor
\begin{equation}
  A_i = a(\phi_{i_1}^1, \phi_{i_2}^2, \ldots, \phi_{i_r}^r).
\end{equation}

In the form language, a multilinear form is defined by first
specifying the set of function spaces,
$V_h^1, V_h^2, \ldots, V_h^r$, and then expressing the multilinear form in
terms of the basis functions of these function spaces.

A function space is defined in the form language through a
\texttt{FiniteElement}, and a corresponding basis function is
represented as a \texttt{BasisFunction}. The following code defines a
pair of basis functions \texttt{v} and \texttt{u} for a first-order
Lagrange finite element on triangles:
\begin{code}
element = FiniteElement("Lagrange", "triangle", 1)
v = BasisFunction(element)
u = BasisFunction(element)
\end{code}
The two basis functions can now be used to define a bilinear form:
\begin{code}
a = v*D(u, 0)*dx
\end{code}
corresponding to the mathematical notation
\begin{equation}
  a(v, u) = \int_{\Omega} v \, \frac{\partial u}{\partial x_0} \dx.
\end{equation}
Note that the order of the argument list of the multilinear form is
determined by the order in which basis functions are declared, not by
the order in which they appear in the form. Thus, both \texttt{a =
v*D(u, 0)*dx} and \texttt{a = D(u, 0)*v*dx} define the same
multilinear form.

The arity (number of arguments) of a multilinear form is determined by
the number of basis functions appearing in the definition of the
form. Thus, \texttt{a = v*u*dx} defines a \textit{bilinear form},
namely $a(v, u) = \int_{\Omega} v \, u \dx$, whereas \texttt{L =
v*dx} defines a \textit{linear form}, namely $L(v) = \int_{\Omega} v
 \dx$.

In the case of a bilinear form, the first of the two basis functions
is referred to as the \textit{test function} and the second is
referred to as the \textit{trial function}. One may optionally use the
keywords \texttt{TestFunction} and \texttt{TrialFunction} to specify
the test and trial functions. This has the advantage that the order of
specification of the two functions does not matter; the test function
will always be the first argument of a bilinear form and correspond to
a row in the corresponding assembled matrix. Thus, the example above
may optionally be specified as follows:
\begin{code}
element = FiniteElement("Lagrange", "triangle", 1)
v = TestFunction(element)
u = TrialFunction(element)
\end{code}

Not every expression is a valid multilinear form. The following list
explains some of the basic rules that must be obeyed in the definition
of a form:
\begin{itemize}
\item
  A form must be linear in each of its arguments; otherwise it is not
  a multilinear form. Thus, \texttt{a = v*v*u*dx} is not a valid
  form, since it is quadratic in \texttt{v}.
\item
  The value of a form must be a scalar. Thus, if \texttt{v} is a
  vector-valued basis function (see below), then \texttt{L = v*dx} is
  not a valid form, since the value of the form is not a scalar.
\item
  The integrand of a form must be integrated exactly once. Thus,
  neither \texttt{a = v*u} nor \texttt{a = v*u*dx*dx} are valid forms.
\end{itemize}

%------------------------------------------------------------------------------
\section{The form language as a Python extension}
\index{Python}

The \ffc{} form language is built on top of Python.  This is true both
when calling \ffc{} as a compiler from the command-line or when
calling the \ffc{} compiler from within a Python program. Through the
addition of a collection of basic data types and operators, \ffc{}
allows a form to be specified in a language that is close to the
mathematical notation. Since the form language is built on top of
Python, any Python code is valid in the definition of a form (but not
all Python code defines a multilinear form). In particular, comments
(lines starting with \texttt{\#}) and functions (keyword \texttt{def},
see Section \ref{sec:user-defined} below) are allowed in the definition
of a form.

%------------------------------------------------------------------------------
\section{Basic data types}

\subsection{\texttt{FiniteElement}}
\index{finite elements}
\index{\texttt{FiniteElement}}
\index{Lagrange element}
\index{discontinuous Lagrange element}

The data type \texttt{FiniteElement} represents a finite element on a
triangle or tetrahedron. A \texttt{FiniteElement} is declared by
specifying the finite element family, the underlying shape and the
polynomial degree:
\small
\begin{code}
element = FiniteElement(family, shape, degree)
\end{code}
\normalsize

The argument \texttt{family} is a string and possible values include:
\begin{itemize}
\item
  \texttt{"Lagrange"} or \texttt{"CG"}, representing standard scalar
  Lagrange finite elements (continuous piecewise polynomial
  functions);
\item
  \texttt{"Discontinuous Lagrange"} or \texttt{"CG"}, representing
  scalar discontinuous Lagrange finite elements (discontinuous
  piecewise polynomial functions);
\item
  \texttt{"Crouzeix-Raviart"} or \texttt{"CR"}, representing scalar
  Crouzeix--Raviart elements;
\item
  \texttt{"Brezzi-Douglas-Marini"} or \texttt{"BDM"}, representing
  vector-valued Brezzi--Douglas--Marini $H(\mathrm{div})$ elements;
\item
  \texttt{"Raviart-Thomas"} or \texttt{"RT"}, representing
  vector-valued Raviart--Thomas $H(\mathrm{div})$ elements.
\end{itemize}

The argument \texttt{shape} is a string and possible values include:
\begin{itemize}
\item
  \texttt{"triangle"}, representing a triangle in $\R^2$;
\item
  \texttt{"tetrahedron"}, representing a tetrahedron in $\R^3$.
\end{itemize}

The argument \texttt{degree} is an integer specifying the polynomial
degree of the finite element. Note that the minimal degree for Lagrange
finite elements is one, whereas the minimal degree for
discontinuous Lagrange finite elements is zero.

Note that more than one \texttt{FiniteElement} can be declared and
used in the definition of a form. The following example declares two
elements, one linear and one quadratic Lagrange finite element:
\begin{code}
P1 = FiniteElement("Lagrange", "tetrahedron", 1)
P2 = FiniteElement("Lagrange", "tetrahedron", 2)
\end{code}

\subsection{\texttt{VectorElement}}
\index{vector elements}
\index{\texttt{VectorElement}}

The data type \texttt{VectorElement} represents a vector-valued
element. Vector-valued elements may be created by repeating any
finite element (scalar, vector-valued or mixed) a given number of
times. The following code demonstrates how to create a vector-valued
cubic Lagrange element on a triangle:
\begin{code}
element = VectorElement("Lagrange", "triangle", 3)
\end{code}
This will create a vector-valued Lagrange element with two
components. If the number of components is not specified, it will
automatically be chosen to be the equal to the cell
dimension. Optionally, one may also specify the number of vector
components directly:
\begin{code}
element = VectorElement("Lagrange", "triangle", 3, 5)
\end{code}

Note that vector-valued elements may be created from any given element
type. Thus, one may create a (nested) vector-valued element with four
components where each pair of components is a first degree BDM element
as follows:
\begin{code}
element = VectorElement("BDM", "triangle", 1, 2)
\end{code}

\subsection{\texttt{MixedElement}}
\index{mixed finite elements}
\index{\texttt{MixedElement}}

The data type \texttt{MixedElement} represents a mixed finite element
on a triangle or tetrahedron. The function space of a mixed finite
element is defined as the direct sum of the function spaces of a
given list of elements. A \texttt{MixedElement} is declared by
specifying a \texttt{list} of \texttt{FiniteElement}s:
\begin{code}
mixed_element = MixedElement([e0, e1, ...])
\end{code}

Alternatively, a \texttt{MixedElement} can be created as the sum of a
pair\footnote{Note that summing more than two elements will create a
nested mixed element. For example \texttt{e = e0 + e1 + e2} will
correspond to \texttt{e = MixedElement([MixedElement([e0, e1]), e2])}.}
of \texttt{FiniteElement}s. The following example illustrates how to
create a Taylor--Hood element (quadratic velocity and linear pressure):
\begin{code}
P2 = VectorElement("Lagrange", "triangle", 2)
P1 = FiniteElement("Lagrange", "triangle", 1)
TH = P2 + P1
\end{code}

Elements may be mixed at arbitrary depth, so mixed elements can be
used as building blocks for creating new mixed elements. In fact, a
\texttt{VectorElement} just provides a simple means to create mixed
elements. Thus, a Taylor--Hood element may also be created as follows:
\begin{code}
P2 = FiniteElement("Lagrange", "triangle", 2)
P1 = FiniteElement("Lagrange", "triangle", 1)
TH = (P2 + P2) + P1
\end{code}

\subsection{\texttt{BasisFunction}}
\index{basis functions}
\index{\texttt{BasisFunction}}
\index{\texttt{BasisFunctions}}

The data type \texttt{BasisFunction} represents a basis function on a
given finite element. A \texttt{BasisFunction} must be created for a
previously declared finite element (simple or mixed):
\begin{code}
v = BasisFunction(element)
\end{code}
Note that more than one \texttt{BasisFunction} can be declared for
the same \texttt{FiniteElement}. Basis functions are associated with the
arguments of a multilinear form in the order of declaration.

For a \texttt{MixedElement}, the function \texttt{BasisFunctions} can
be used to construct tuples of \texttt{BasisFunction}s, as illustrated here
for a mixed Taylor--Hood element:
\begin{code}
(v, q) = BasisFunctions(TH)
(u, p) = BasisFunctions(TH)
\end{code}

\subsection{\texttt{TestFunction} and \texttt{TrialFunction}}

The data types \texttt{TestFunction} and \texttt{TrialFunction} are
special instances of \texttt{BasisFunction} with the property that a
\texttt{TestFunction} will always be the first argument in a form and
\texttt{TrialFunction} will always be the second argument in a form
(order of declaration does not matter).

For a \texttt{MixedElement}, the functions \texttt{TestFunctions} and
\texttt{TrialFunctions} can be used to construct tuples of
\texttt{TestFunction}s and \texttt{TrialFunction}s, as illustrated here
for a mixed Taylor--Hood element:
\begin{code}
(v, q) = TestFunctions(TH)
(u, p) = TrialFunctions(TH)
\end{code}

\subsection{\texttt{Function}}
\index{functions}
\index{\texttt{Function}}
\index{\texttt{Functions}}

The data type \texttt{Function} represents a function belonging to a
given finite element space, that is, a linear combination of basis
functions of the finite element space. A \texttt{Function} must be
declared for a previously declared \texttt{FiniteElement}:
\begin{code}
f = Function(element)
\end{code}

Note that more than one function can be declared for
the same \texttt{FiniteEle\-ment}. The following example declares two
\texttt{BasisFunction}s and two \texttt{Function}s for the same
\texttt{FiniteElement}:
\begin{code}
v = BasisFunction(element)
u = BasisFunction(element)
f = Function(element)
g = Function(element)
\end{code}

\texttt{Function} is used to represent user-defined functions,
including right-hand sides, variable coefficients and stabilization
terms. \ffc{} treats each \texttt{Function} as a linear combination of
basis functions with unknown coefficients. It is the responsibility of
the user or the system for which the form is compiled to supply the
values of the coefficients at run-time. In the case of \dolfin{}, the
coefficients are automatically computed from a given user-defined
function during the assembly of a form. In the notation of the UFC
interface~\cite{www:ufc,ufcmanual}, \texttt{Function}s are referred to
as \emph{coefficients}.

Note that the order in which \texttt{Function}s are declared is
important. The code generated by \ffc{} accepts as arguments a list of
functions that should correspond to the \texttt{Function}s appearing
in the form in the order they have been declared.

For a \texttt{MixedElement}, the function \texttt{Functions} can
be used to construct tuples of \texttt{Function}s, as illustrated here
for a mixed Taylor--Hood element:
\begin{code}
(f, g) = Functions(TH)
\end{code}