\chapter{Python interface}

\ffc{} provides a Python interface in the form of a standard
Python module. The following example demonstrates how to define and
compile the variational problem for Poisson's equation in a Python
script:

\begin{code}
from ffc import *

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

compile([a, L], "Poisson")
\end{code}

At the basic level, the only difference between the command-line
interface and the Python interface is that one must add the
import statement of the \ffc{} module and that the function
\texttt{compile} must be called when using the Python interface.

\section{Compiling forms: \texttt{compile}}

The \texttt{compile} function expects a form (see
Section~\ref{sec:formlanguage}) or a list of forms as its first
argument. It also accepts up to four additional optional arguments:
\begin{code}
compile(forms, prefix, representation, language, options)
\end{code}

\subsection{Input arguments}

The \texttt{prefix} argument can be used to control the prefix of the
file containing the generated code, which we in the above example set
to \texttt{"Poisson"}. The suffix \texttt{".h"} will be added
automatically.

The \texttt{representation} argument can be used to control the form
representation used for precomputation and code generation. The
default value is \texttt{"tensor"}, which indicates that the code
should be generated based on a tensor representation of the
multilinear form as described
in~\cite{KirLog06,KirLog07}. Alternatively, \texttt{"quadrature"} may be
used to specify that code should be generated based on direct
quadrature at run-time (experimental).

The \texttt{language} option can be used to control the output
language for the generated code. The default value is \texttt{"ufc"},
which indicates that code should be generated in the UFC
format~\cite{www:ufc,ufcmanual}. Alternatively, \texttt{"dolfin"} may
be used to generate code according to the UFC format with a small set
of additional \dolfin{}-specific wrappers.

The \texttt{compile} function accepts a dictionary of special
code generation options. The default values for these options may be
accessed through the variable \texttt{FFC\_OPTIONS} available in
\ffc{}.

\subsection{Output arguments}

The \texttt{compile} function returns a tuple
\begin{code}
(form_data, form_representation)
\end{code}
where \texttt{form\_data} is a list of metadata
extracted for each input form and where \texttt{form\_representation}
is a list that holds a particular internal representation of each
input form. The form representation depends on the chosen
representation mode. Accessing this data is mainly intended for
developers.

\subsection{Compiling finite elements}

The \texttt{compile} function may also be used to compile finite
elements directly (without associated forms). The following example
demonstrates how to generate code for a fifth degree Lagrange finite
element on tetrahedra:
\begin{code}
from ffc import *

element = FiniteElement("Lagrange", "tetrahedron", 5)
compile(element, "P5")
\end{code}

\section{Just-in-time (JIT) compiler: \texttt{jit}}

The \texttt{jit} function expects a single form
as its first argument. It also accepts up to three additional optional arguments:
\begin{code}
jit(form, representation, language, options)
\end{code}
However, instead of generating code, the \texttt{jit} function returns
the \emph{compiled} form as a Python object. It does this by
generating code, compiling it (by calling the C++ compiler) and
wrapping it as a Python module (by calling Instant/SWIG).

The \texttt{jit} function returns a tuple
\begin{code}
(compiled_form, compiled_module, form_data)
\end{code}
where \texttt{compiled\_form} is the compiled form (a Python wrapper
for \texttt{ufc::form}), \texttt{compiled\_module} is a Python module
containing the compiled form, finite elements, dof maps etc (a Python
wrapper for the complete set of generated code), and
\texttt{form\_data} is form metadata generated from the input form.

The JIT compiler caches generated modules such that if a Python script
including a call to the JIT compiler is run twice (in the same
directory) the Python module is only generated once. The generated
modules are stored in a cache directory defined by Instant. To clean
the cache, run the command \texttt{instant-clean}.
