\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 an interval,
triangle or tetrahedron. A \texttt{FiniteElement} is declared by
specifying the finite element family, the underlying shape and the
polynomial degree:
\begin{code}
element = FiniteElement(family, shape, degree)
\end{code}

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{"Brezzi-Douglas-Fortin-Marini"} or \texttt{"BDFM"}, representing
  vector-valued Brezzi--Douglas--Fortin--Marini $H(\mathrm{div})$ elements;
\item
  \texttt{"Raviart-Thomas"} or \texttt{"RT"}, representing
  vector-valued Raviart--Thomas $H(\mathrm{div})$ elements.
\item
  \texttt{"Nedelec"}, representing
  vector-valued Nedelec $H(\mathrm{curl})$ elements (of the first kind).
\end{itemize}

The argument \texttt{shape} is a string and possible values include:
\begin{itemize}
\item
  \texttt{"interval"}, representing an interval in $\R^1$;
\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 an interval, 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{QuadratureElement}}
\index{\texttt{QuadratureElement}}
\index{\texttt{VectorQuadratureElement}}

The data type \texttt{QuadratureElement} is different from the
\texttt{FiniteElement} in the sense that it represents discrete
function values rather than a finite element space, i.e., it can be
used to define functions that do not come from a finite element
space. Apart from this, the class \texttt{QuadratureElement} can be
used in the same way as the class \texttt{FiniteElement} with the only
difference that it is not possible to take derivatives of a function
which is defined on a \texttt{QuadratureElement}.

A \texttt{QuadratureElement} is declared by
specifying the underlying shape and the number of values (integration points)
in each dimension:
\begin{code}
element = QuadratureElement(shape, num_points)
\end{code}

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

The argument \texttt{num\_points} is an integer specifying the number
of values in each dimension. Thus the following element:
\begin{code}
element = QuadratureElement("triangle", 3)
\end{code}
returns an element with $3\times 3$ values on a
triangle. The coordinates of these values coincide with the
coordinates of the $3\times 3$ integration scheme returned by
\fiat{}. This element is useful in cases where quantities should be
evaluated at quadrature points (rather than interpolated at nodal
points). An example is given in Section~\ref{sec:examples}.

It is also possible to construct mixed elements from a
\texttt{QuadratureElement}, and for convenience the
\texttt{VectorQuadratureElement} is available with the same basic
functionality as the \texttt{VectorElement}. The only difference is
that the \texttt{VectorQuadratureElement} will return a vector-valued
element based on the \texttt{QuadratureElement}.

\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}

\subsection{\texttt{Constant}}
\index{constants}
\index{\texttt{Constant}}

The data type \texttt{Constant} represents a constant scalar value
that is unknown at compile-time. A \texttt{Constant} is declared
for a given cell shape (\texttt{"interval"}, \texttt{"triangle"} or
\texttt{"tetrahedron"}):
\begin{code}
c = Constant(shape)
\end{code}
\texttt{Constant}s are automatically replaced by (discontinuous)
piecewise constant \texttt{Function}s. The following two declarations
are thus equivalent:
\begin{code}
DG0 = FiniteElement("Discontinuous Lagrange", "triangle", 0)

c0 = Constant("triangle")
c1 = Function(DG0)
\end{code}

\subsection{\texttt{VectorConstant}}
\index{vector constants}
\index{\texttt{VectorConstant}}

The data type \texttt{VectorConstant} represents a constant vector value
that is unknown at compile-time. A \texttt{VectorConstant} is declared
for a given cell shape (\texttt{"interval"}, \texttt{"triangle"} or
\texttt{"tetrahedron"}):
\begin{code}
c = VectorConstant(shape)
\end{code}
\texttt{VectorConstant}s are automatically replaced by (discontinuous)
vector-valued piecewise constant \texttt{Function}s. The following two
declarations are thus equivalent:
\begin{code}
DG0 = VectorElement("Discontinuous Lagrange", "triangle", 0)

c0 = VectorConstant("triangle")
c1 = Function(DG0)
\end{code}

\subsection{\texttt{Index}}
\index{indices}
\index{\texttt{Index}}

The data type \texttt{Index} represents an index used for subscripting
derivatives or taking components of vector-valued functions.
If an \texttt{Index} is declared without any arguments,
\begin{code}
i = Index()
\end{code}
a \textit{free} \texttt{Index} is created, representing an
\textit{index range} determined by the context; if used to subscript a
vector-valued \texttt{BasisFunction} or a \texttt{Function}, the range
is given by the number of vector dimensions $n$, and if used to subscript
a derivative, the range is given by the dimension $d$ of the underlying
shape of the finite element space. As we shall see below, indices can
be a powerful tool when used to define forms in tensor notation.

An \texttt{Index} can also be \textit{fixed}, meaning that the value
of the index remains constant:
\begin{code}
i = Index(0)
\end{code}

\subsection{Built-ins}

\ffc{} declares a set of built-in variables and constructors for
convenience, as outlined below.

\subsubsection{Predefined indices}

\ffc{} automatically declares a sequence of free indices
for convenience: \texttt{i}, \texttt{j}, \texttt{k}, \texttt{l},
\texttt{m}, \texttt{n}. Note however that a user is free to declare
new indices with other names or even reuse these variables for other
things than indices.

\subsubsection{\texttt{Identity}}
\index{identity matrix}
\index{\texttt{Identity}}

The data type \texttt{Identity} represents an $n\times n$ unit matrix
of given size $n$.  An \texttt{Identity} is declared by specifying the
dimension $n$:
\begin{code}
I = Identity(n)
\end{code}

\subsubsection{\texttt{MeshSize}}
\index{mesh size}
\index{\texttt{MeshSize}}

The function \texttt{MeshSize} is a predefined \texttt{Function} that
may be used to represent the size of the mesh:
\begin{code}
h = MeshSize(shape)
\end{code}
Note that it is the
responsibility of the user (or the system for which the code is
generated) to map this function to a function (coefficient) that
interpolates the mesh size onto piecewise constants.

\subsubsection{\texttt{FacetNormal}}
\index{facet normal}
\index{\texttt{FacetNormal}}

The function \texttt{FacetNormal} is a predefined \texttt{Function} that
may be used to represent the unit normals of mesh facets.
\begin{code}
n = FacetNormal(shape)
\end{code}
Note that it is the responsibility of the user (or the system for
which the code is generated) to map this function to a function
(coefficient) that interpolates the facet normals onto vector-valued
piecewise constants.

%------------------------------------------------------------------------------
\section{Scalar operators}
\index{scalar operators}

The basic operators used to define a form are scalar addition,
subtraction and multiplication. Note the absence of division
which is intentionally left out (but is supplied for
\texttt{Function}s, see below).

\subsection{Scalar addition: \texttt{+}}
\index{addition}

Scalar addition is supported for all scalar-valued basic data types,
thus including \texttt{BasisFunction}, \texttt{Function},
\texttt{Constant} and expressions involving these data types.

In addition, unary plus is supported for all basic data types.

\subsection{Scalar subtraction: \texttt{-}}
\index{subtraction}

Scalar subtraction is supported for all scalar-valued basic data types,
thus including \texttt{BasisFunction}, \texttt{Function},
\texttt{Constant} and expressions involving these data types.

In addition, unary minus is supported for all basic data types.

\subsection{Scalar multiplication: \texttt{*}}
\index{multiplication}

Scalar multiplication is supported for all scalar-valued basic data types,
thus including \texttt{BasisFunction}, \texttt{Function},
\texttt{Constant} and expressions involving these data types.

\subsection{Scalar division: \texttt{/}}
\index{division}

Division is not allowed for \texttt{BasisFunction}s (and thus not for
\texttt{TestFunction}s and \texttt{TrialFunction}s) in the definition
of a form. This is because division by a \texttt{BasisFunction} in the
definition of a form does not result in a valid multilinear form,
since a multilinear form must be linear in each of its
arguments.

However, division is allowed for \texttt{Function}s and is applied to
the coefficients of its nodal basis expansion. Thus \texttt{1/f} for a
\texttt{Function} \texttt{f} corresponds to the operation
\begin{equation}
  1/f \approx \sum_i (1/f_i)  \, \phi_i.
\end{equation}
See also Section~\ref{sec:specialoperators}.

%------------------------------------------------------------------------------
\section{Vector operators}
\index{vector operators}

Vectors are defined in the form language using Python's built-in
\texttt{list} type. This means that all list operations such as
slicing, list comprehension etc. are supported. There is one exception
to this rule, namely vector-valued \texttt{BasisFunction}s and
\texttt{Function}s, which are not \texttt{list}s (but can be made into
\texttt{list}s using the operator \texttt{vec} discussed below).
The operators listed below support all objects which are logically
vectors, thus including both Python \texttt{list}s and vector-valued
expressions.

\subsection{Component access: \texttt{v[i]}}
\index{component access}
\index{subscripting}

Brackets \texttt{[]} are used to pick a given component of a logically
vector-valued expression. Thus, if \texttt{v} is a vector-valued
expression, then \texttt{v[0]} represents a function
corresponding to the first component of (the values of) \texttt{v}.
Similarly, if \texttt{i} is an \texttt{Index} (free or fixed), then
\texttt{v[i]} represents a function corresponding to component
\texttt{i} of (the values of) \texttt{v}.

\subsection{Inner product: \texttt{dot(v, w)}}
\index{inner product}
\index{\texttt{dot}}

The operator \texttt{dot} accepts as arguments two logically
vector-valued expressions and returns the inner product (dot product)
of the two vectors:
\begin{equation}
  \mbox{\texttt{dot(v, w)}} \leftrightarrow v \cdot w =
  \sum_{i=0}^{n-1} v_i w_i.
\end{equation}
Note that this operator is only defined for vectors of equal length.

\subsection{Vector product: \texttt{cross(v, w)}}
\index{vector product}
\index{cross product}
\index{\texttt{cross}}

The operator \texttt{cross} accepts as arguments two logically
vector-valued expressions and returns a vector which is the cross
product (vector product) of the two vectors:
\begin{equation}
  \mbox{\texttt{cross(v, w)}} \leftrightarrow v \times w =
  (v_1 w_2 - v_2 w_1, v_2 w_0 - v_0 w_2, v_0 w_1 - v_1 w_0).
\end{equation}
Note that this operator is only defined for vectors of length three.

\subsection{Matrix product: \texttt{mult(v, w)}}
\index{matrix product}

The operator \texttt{mult} accepts as arguments two matrices (or more
generally, tensors) and returns the matrix (tensor) product.

\subsection{Transpose: \texttt{transp(v)}}
\index{transpose}
\index{\texttt{transp}}

The operator \texttt{transp} accepts as argument a matrix and returns
the transpose of the given matrix:
\begin{equation}
  \mbox{\texttt{transp(v)[i][j]}} \leftrightarrow (v^{\top})_{ij} = v_{ji}.
\end{equation}

\subsection{Trace: \texttt{trace(v)}}
\index{trace}
\index{\texttt{trace}}

The operator \texttt{trace} accepts as argument a square matrix \texttt{v}
and returns its trace, that is, the sum of its diagonal elements:
\begin{equation}
  \mbox{\texttt{trace}(v)} \leftrightarrow \mathrm{trace}(v) = \sum_{i=0}^{n-1} v_{ii}.
\end{equation}

\subsection{Vector length: \texttt{len(v)}}
\index{vector length}
\index{\texttt{len}}

The operator \texttt{len} accepts as argument a logically
vector-valued expression and returns its length (the number of vector
components).

\subsection{Rank: \texttt{rank(v)}}
\index{vector rank}
\index{\texttt{rank}}

The operator \texttt{rank} returns the rank of the given argument. The
rank of an expression is defined as the number of times the operator
\texttt{[]} can be applied to the expression before a scalar is
obtained. Thus, the rank of a scalar is zero, the rank of a vector is
one and the rank of a matrix is two.

\subsection{Vectorization: \texttt{vec(v)}}
\index{vectorization}
\index{\texttt{vec}}

The operator \texttt{vec} is used to create a Python \texttt{list}
object from a logically vector-valued expression. This operator has no
effect on expressions which are already \texttt{list}s. Thus, if
\texttt{v} is a vector-valued \texttt{BasisFunction}, then
\texttt{vec(v)} returns a list of the components of \texttt{v}. This
can be used to define forms in terms of standard Python \texttt{list}
operators or Python NumPy \texttt{array} operators.

The operator \texttt{vec} does not have to be used if the form is
defined only in terms of the basic operators of the form language.

%------------------------------------------------------------------------------
\section{Differential operators}
\index{differential operators}

\subsection{Scalar partial derivative: \texttt{D(v, i)}}
\index{partial derivative}
\index{\texttt{D}}

The basic differential operator is the scalar partial derivative
\texttt{D}. This differential operator accepts as arguments a scalar
or logically vector-valued expression \texttt{v} together with a
coordinate direction \texttt{i} and returns the partial derivative of
the expression in the given coordinate direction:
\begin{equation}
  \mbox{\texttt{D(v, i)}} \leftrightarrow \frac{\partial v}{\partial x_i}.
\end{equation}

Alternatively, the member function \texttt{dx} can be used. For
\texttt{v} an expression, the two expressions \texttt{D(v, i)} and
\texttt{v.dx(i)} are equivalent, but note that only the operator
\texttt{D} works on vector-valued expressions that are defined in
terms of Python lists.

\subsection{Gradient: \texttt{grad(v)}}
\index{gradient}
\index{\texttt{grad}}

The operator \texttt{grad} accepts as argument an expression
\texttt{v} and returns its gradient. If \texttt{v} is scalar, the
result is a vector containing the partial derivatives in the
coordinate directions:
\begin{equation}
  \mbox{\texttt{grad(v)}} \leftrightarrow \mathrm{grad(v)} = \nabla v = 
  (\frac{\partial v}{\partial x_0}, \frac{\partial v}{\partial x_1},
  \ldots, \frac{\partial v}{\partial x_{d-1}}).
\end{equation}
If \texttt{v} is logically vector-valued, the result is a matrix with
rows given by the gradients of each component:
\begin{equation}
  \mbox{\texttt{grad(v)}}[i][j] \leftrightarrow
  \left(\mathrm{grad(v)}\right)_{ij} =
  \left(\nabla v\right)_{ij} =
  \frac{\partial v_i}{\partial x_j}.
\end{equation}
Thus, if \texttt{v} is scalar-valued, then \texttt{grad(grad(v))}
returns the Hessian of \texttt{v}, and if \texttt{v} is vector-valued,
then \texttt{grad(v)} is the Jacobian of \texttt{v}.
\index{Hessian}\index{Jacobian}

\subsection{Divergence: \texttt{div(v)}}
\index{divergence}
\index{\texttt{div}}

The operator \texttt{div} accepts as argument a logically
vector-valued expression and returns its divergence:
\begin{equation}
  \mbox{\texttt{div(v)}} \leftrightarrow \mathrm{div} \, v = \nabla \cdot v =
  \sum_{i=0}^{d-1} \frac{\partial v_i}{\partial x_i}.
\end{equation}
Note that the length $n$ of the vector \texttt{v} must be equal to the
dimension $d$ of the underlying shape of the \texttt{FiniteElement}
defining the function space for~\texttt{v}.

\subsection{Curl: \texttt{curl(v)}}
\index{rotation}
\index{curl}
\index{\texttt{curl}}
\index{\texttt{rot}}

The operator \texttt{curl} accepts as argument a logically
vector-valued expression and returns its curl:
\begin{equation}
  \mbox{\texttt{curl(v)}} \leftrightarrow \mathrm{curl} \, v = \nabla \times v
  = (\frac{\partial v_2}{\partial x_1} - \frac{\partial v_1}{\partial x_2},
  \frac{\partial v_0}{\partial x_2} - \frac{\partial v_2}{\partial x_0},
  \frac{\partial v_1}{\partial x_0} - \frac{\partial v_0}{\partial x_1}).
\end{equation}
Note that this operator is only defined for vectors of length three.

Alternatively, the name \texttt{rot} can be used for this operator.

%------------------------------------------------------------------------------
\section{Integrals}
\index{integrals}

Each term of a valid form expression must be a scalar-valued
expression integrated exactly once. Integrals are expressed through
multiplication with a measure, representing either an integral over
the interior of the domain $\Omega$ (cell integral), the boundary
$\partial \Omega$ of $\Omega$ (exterior facet integral) or the set of
interior facets (interior facet integral).

\subsection{Cell integrals: \texttt{*dx}}
\index{interior measure}
\index{cell integral}

A measure for integration over the interior of $\Omega$ is created as
follows:
\begin{code}
dx = Integral("cell")
\end{code}

For convenience, \ffc{} automatically declares the measure
\texttt{dx} which can be used to define cell integrals.
If \texttt{v} is a scalar-valued expression, then the integral of
\texttt{v} over the interior of $\Omega$ is written as \texttt{v*dx}.

\subsection{Exterior facet integrals: \texttt{*ds}}
\index{boundary measure}
\index{exterior facet integral}

A measure for integration over the boundary of $\Omega$ is created as
follows:
\begin{code}
ds = Integral("exterior facet")
\end{code}

For convenience, \ffc{} automatically declares the measure \texttt{ds}
which can be used to define cell integrals. If \texttt{v} is a
scalar-valued expression, then the integral of \texttt{v} over the
boundary of $\Omega$ is written as \texttt{v*ds}.

\subsection{Interior facet integrals: \texttt{*dS}}
\index{boundary measure}
\index{interior facet integral}

A measure for integration over the set of interior facets of $\Omega$ is created as
follows:
\begin{code}
dS = Integral("interior facet")
\end{code}

For convenience, \ffc{} automatically declares the measure
\texttt{dS} which can be used to define cell integrals.
If \texttt{v} is a scalar-valued expression, then the integral of
\texttt{v} over the interior facets of $\Omega$ is written as \texttt{v*dS}.

\subsection{Integrals over subsets}

Integrals over multiple disjoint subdomains of $\Omega$ may be defined
by specifying an additional argument for the number of the subdomain
associated with each integral. The different measures may then be
combined to express a form as a sum of integrals over the different
subdomains.
\begin{code}
dx0 = Integral("cell", 0)
dx1 = Integral("cell", 1)

ds0 = Integral("exterior facet", 0)
ds1 = Integral("exterior facet", 1)
ds2 = Integral("exterior facet", 2)

dS0 = Integral("interior facet", 0)

a = ...*dx0 + ...*dx1 + ...*ds0 + ...*ds1 + ...*ds2 + ...*dS0
\end{code}

%------------------------------------------------------------------------------
\section{DG operators}
\index{DG operators}
\index{discontinuous Galerkin}

\ffc{} provides operators for implementation of discontinuous Galerkin
methods. These include the evaluation of the jump and average
of a function (or in general an expression) over the interior facets
(edges or faces) of a mesh.

\subsection{Restriction: \texttt{v('+')} and \texttt{v('-')}}

When integrating over interior facets (\texttt{*dS}), one may restrict
expressions to the positive or negative side of the facet:
\begin{code}
element = FiniteElement("Discontinuous Lagrange", 
                        "tetrahedron", 0)

v = TestFunction(element)
u = TrialFunction(element)

f = Function(element)

a = f('+')*dot(grad(v)('+'), grad(u)('-'))*dS
\end{code}

Restriction may be applied to functions of any finite element space
but will only have effect when applied to expressions that are
discontinuous across facets.

\subsection{Jump: \texttt{jump(v)}}

The operator \texttt{jump} may be used to express the jump of a
function across a common facet of two cells. Two versions of the
\texttt{jump} operator are provided.

If called with only one argument, then the \texttt{jump} operator
evaluates to the difference between the restrictions of the given
expression on the positive and negative sides of the facet:
\begin{equation}
  \mbox{\texttt{jump(v)}}
  \leftrightarrow
  \llbracket v \rrbracket = v^+ - v^-.
\end{equation}
If the expression \texttt{v} is scalar, then \texttt{jump(v)} will
also be scalar, and if \texttt{v} is vector-valued, then \texttt{jump(v)}
will also be vector-valued.

If called with two arguments, \texttt{jump(v, n)} evaluates to the
jump in \texttt{v} weighted by \texttt{n}. Typically, \texttt{n} will
be chosen to represent the unit outward normal of the facet (as seen
from each of the two neighboring cells). If \texttt{v} is scalar, then
\texttt{jump(v, n)} is given by
\begin{equation}
  \mbox{\texttt{jump(v, n)}}
  \leftrightarrow
  \llbracket v \rrbracket_n = v^+ n^+ + v^- n^-.
\end{equation}
If \texttt{v} is vector-valued, then \texttt{jump(v, n)} is given by
\begin{equation}
  \mbox{\texttt{jump(v, n)}}
  \leftrightarrow
  \llbracket v \rrbracket_n = v^+ \cdot n^+ + v^- \cdot n^-.
\end{equation}
Thus, if the expression \texttt{v} is scalar, then \texttt{jump(v, n)} will
be vector-valued, and if \texttt{v} is vector-valued, then
\texttt{jump(v, n)} will be scalar.

\subsection{Average: \texttt{avg(v)}}

The operator \texttt{avg} may be used to express the average of a
function across a common facet of two cells:
\begin{equation}
  \mbox{avg(v)}
  \leftrightarrow
  \langle v \rangle = \frac{1}{2} (v^+ + v^-).
\end{equation}
If the expression \texttt{v} is scalar, then \texttt{avg(v)} will
also be scalar, and if \texttt{v} is vector-valued, then \texttt{avg(v)}
will also be vector-valued.

%------------------------------------------------------------------------------
\section{Special operators}
\label{sec:specialoperators}
\index{special operators}
\index{inverse}
\index{absolute value}
\index{\texttt{abs}}
\index{square root}
\index{\texttt{sqrt}}

\ffc{} provides a set of special operators for taking the inverse,
absolute value and square root of an expression. These operators are
interpreted in a special way and should be used with care.  Firstly,
the operators are only valid on monomial expressions, that is,
expressions that consist of only one term. Secondly, the operators are
applied directly to the \emph{coefficients} of the basis function
expansion of the expression on which the operators are applied.
Thus, if $v = \sum_i v_i \phi_i$, then $\mathrm{op}(v)$ is
evaluated by
\begin{equation}
  \mathrm{op}(v) = \sum_i \mathrm{op}(v_i) \phi_i.
\end{equation}


\subsection{Inverse: \texttt{1/v}}

The inverse of a monomial expression (for example a product of one or
more functions) may be evaluated (in the sense described above) as
follows:
\begin{code}
w = 1/v
\end{code}

\subsection{Modulus: \texttt{modulus(v)}}

The modulus, i.e. the absolute value, of a monomial expression (for
example a product of one or more functions) may be evaluated (in the
sense described above) as follows:
\begin{code}
w = modulus(v)
\end{code}

\subsection{Square root: \texttt{sqrt(v)}}

The square root of a monomial expression (for example a product of one or
more functions) may be evaluated (in the sense described above) as
follows:
\begin{code}
w = sqrt(v)
\end{code}

\subsection{Combining operators}

The special operators may applied successively and repeatedly on any
monomial expression. Thus, the following expression is valid:
\begin{code}
v = Function(element)
w = sqrt(abs(1/v))
\end{code}

%------------------------------------------------------------------------------
\section{Index notation}
\index{index notation}

\ffc{} supports index notation, which is often a convenient way to
express forms. The basic principle of index notation is that summation
is implicit over indices repeated twice in each term of an expression.
The following examples illustrate the index notation, assuming that
each of the variables \texttt{i} and \texttt{j} have been declared as
a free \texttt{Index}:
\begin{eqnarray}
  \mbox{\texttt{v[i]*w[i]}} &\leftrightarrow& \sum_{i=0}^{n-1} v_i w_i, \\
  \mbox{\texttt{D(v, i)*D(w, i)}} &\leftrightarrow&
  \sum_{i=0}^{d-1}
  \frac{\partial v}{\partial x_i} 
  \frac{\partial w}{\partial x_i} = \nabla v \cdot \nabla w, \\
  \mbox{\texttt{D(v[i], i)}} &\leftrightarrow& \sum_{i=0}^{d-1}
  \frac{\partial v_i}{\partial x_i} = \nabla \cdot v, \\
  \mbox{\texttt{D(v[i], j)*D(w[i], j)}} &\leftrightarrow&
  \sum_{i=0}^{n-1} \sum_{j=0}^{d-1}
  \frac{\partial v_i}{\partial x_j} \frac{\partial w_i}{\partial x_j}.
\end{eqnarray}

Index notation is used internally by \ffc{} to represent multilinear
forms and \ffc{} will try to simplify forms by replacing sums with
index expressions.

%------------------------------------------------------------------------------
\section{User-defined operators}
\label{sec:user-defined}
\index{user-defined operators}

A user may define new operators, using standard Python syntax. As an
example, consider the strain-rate operator $\epsilon$ of linear elasticity,
defined by
\begin{equation}
  \epsilon(v) = \frac{1}{2} (\nabla v + (\nabla v)^{\top}).
\end{equation}
This operator can be implemented as a function using the Python \texttt{def}
keyword:
\begin{code}
def epsilon(v):
    return 0.5*(grad(v) + transp(grad(v)))
\end{code}
Alternatively, using the shorthand \texttt{lambda} notation, the
strain operator may be defined as follows:
\begin{code}
epsilon = lambda v: 0.5*(grad(v) + transp(grad(v)))
\end{code}
\index{def}\index{lambda}
