formlanguage.tex

finite element library for mathematic majored research

\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{"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{"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}}).