quickstart.tex

finite element library for mathematic majored research

\chapter{Quickstart}
\index{quickstart}

This chapter demonstrates how to get started with \ffc{}, including
downloading and installing the latest version of \ffc{}, and compiling
Poisson's equation. These topics are discussed in more detail
elsewhere in this manual. In particular, see
Appendix~\ref{app:installation} for detailed installation instructions
and Chapter~\ref{sec:formlanguage} for a detailed discussion of the
form language.

%------------------------------------------------------------------------------
\section{Downloading and installing \ffc{}}
\index{downloading}
\index{installation}

The latest version of \ffc{} can be found on the \fenics{} web page:
\begin{code}
http://www.fenics.org/
\end{code}
The following commands illustrate the installation process, assuming
that you have downloaded release \texttt{x.y.z} of \ffc{}:
\begin{code}
# tar zxfv ffc-x.y.z.tar.gz
# cd ffc-x.y.z
# sudo python setup.py install
\end{code}
Make sure that you download the latest release.
You may also need to install the Python packages \fiat{} and
NumPy. (See Appendix~\ref{app:installation} for detailed instructions.)
\index{FIAT}
\index{Numeric}

%------------------------------------------------------------------------------
\section{Compiling Poisson's equation with \ffc{}}
\index{Poisson's equation}

The discrete variational (finite element) formulation of Poisson's
equation, $-\Delta u = f$, reads: Find $u_h \in V_h$ such that
\begin{equation} \label{eq:varform}
  a(v, u_h) = L(v) \quad \forall v\in \hat{V}_h, 
\end{equation}
with $(\hat{V}_h, V_h)$ a pair of suitable function spaces (the test and
trial spaces). The bilinear form $a : \hat{V}_h \times V_h \rightarrow
\R$ is given by
\begin{equation}
  a(v, u_h) = \int_{\Omega} \nabla v \cdot \nabla u_h \dx
\end{equation}
and the linear form $L : \hat{V}_h \rightarrow \R$ is given by
\begin{equation}
  L(v) = \int_{\Omega} v \, f \dx.
\end{equation}

To compile the pair of forms $(a, L)$ into code that can called to
assemble the linear system $A x = b$ corresponding to the variational
problem (\ref{eq:varform}) for a pair of discrete function spaces,
specify the forms in a text file with extension \texttt{.form},
e.g. \texttt{Poisson.form}, as follows:
\begin{code}
element = FiniteElement("Lagrange", "triangle", 1)

v = TestFunction(element)
u = TrialFunction(element)
f = Function(element)
  
a = dot(grad(v), grad(u))*dx
L = v*f*dx
\end{code}

The example is given for piecewise linear finite elements in two
dimensions, but other choices are available, including arbitrary order
Lagrange elements in two and three dimensions.

To compile the pair of forms implemented in the file
\texttt{Poisson.form}, call the compiler on the command-line as
follows:
\begin{code}
# ffc Poisson.form
\end{code}
This will generate the file \texttt{Poisson.h} containing low level
C++ code in the UFC (Unified Form-assembly Code)
format~\cite{www:ufc,ufcmanual}. The generated code can be used by
any UFC-based assembler such as \dolfin{}~\cite{www:dolfin} to
assemble the discrete representations (the matrix~$A$ and vector~$b$)
of the bilinear form $a$ and linear form~$L$ of Poisson's equation.

Note that by adding the flag \texttt{-l dolfin}, additional
\dolfin{}-specific wrappers are added to the generated code which
simplifies the use of the generated code with \dolfin{}. In
particular, the handling of forms depending on coefficients like $f$
in Poisson's equation is simplified.

For further help on the \texttt{ffc} command and available
command-line options, refer to the \ffc{} man page:
\begin{code}
# man ffc
\end{code}
\index{ffc}
\index{man page}