1
\chapter{Python interface}
3
\ffc{} provides a Python interface in the form of a standard
4
Python module. The following example demonstrates how to define and
5
compile the variational problem for Poisson's equation in a Python
11
element = FiniteElement("Lagrange", "triangle", 1)
13
v = TestFunction(element)
14
u = TrialFunction(element)
17
a = dot(grad(v), grad(u))*dx
20
compile([a, L], "Poisson")
23
At the basic level, the only difference between the command-line
24
interface and the Python interface is that one must add the
25
import statement of the \ffc{} module and that the function
26
\texttt{compile} must be called when using the Python interface.
28
\section{Compiling forms: \texttt{compile}}
30
The \texttt{compile} function expects a form (see
31
Section~\ref{sec:formlanguage}) or a list of forms as its first
32
argument. It also accepts up to four additional optional arguments:
34
compile(forms, prefix, representation, language, options)
37
\subsection{Input arguments}
39
The \texttt{prefix} argument can be used to control the prefix of the
40
file containing the generated code, which we in the above example set
41
to \texttt{"Poisson"}. The suffix \texttt{".h"} will be added
44
The \texttt{representation} argument can be used to control the form
45
representation used for precomputation and code generation. The
46
default value is \texttt{"tensor"}, which indicates that the code
47
should be generated based on a tensor representation of the
48
multilinear form as described
49
in~\cite{KirLog06,KirLog07}. Alternatively, \texttt{"quadrature"} may be
50
used to specify that code should be generated based on direct
51
quadrature at run-time (experimental).
53
The \texttt{language} option can be used to control the output
54
language for the generated code. The default value is \texttt{"ufc"},
55
which indicates that code should be generated in the UFC
56
format~\cite{www:ufc,ufcmanual}. Alternatively, \texttt{"dolfin"} may
57
be used to generate code according to the UFC format with a small set
58
of additional \dolfin{}-specific wrappers.
60
The \texttt{compile} function accepts a dictionary of special
61
code generation options. The default values for these options may be
62
accessed through the variable \texttt{FFC\_OPTIONS} available in
65
\subsection{Output arguments}
67
The \texttt{compile} function returns a tuple
69
(form_data, form_representation)
71
where \texttt{form\_data} is a list of metadata
72
extracted for each input form and where \texttt{form\_representation}
73
is a list that holds a particular internal representation of each
74
input form. The form representation depends on the chosen
75
representation mode. Accessing this data is mainly intended for
78
\subsection{Compiling finite elements}
80
The \texttt{compile} function may also be used to compile finite
81
elements directly (without associated forms). The following example
82
demonstrates how to generate code for a fifth degree Lagrange finite
83
element on tetrahedra:
87
element = FiniteElement("Lagrange", "tetrahedron", 5)
88
compile(element, "P5")
91
\section{Just-in-time (JIT) compiler: \texttt{jit}}
93
The \texttt{jit} function expects a single form
94
as its first argument. It also accepts up to three additional optional arguments:
96
jit(form, representation, language, options)
98
However, instead of generating code, the \texttt{jit} function returns
99
the \emph{compiled} form as a Python object. It does this by
100
generating code, compiling it (by calling the C++ compiler) and
101
wrapping it as a Python module (by calling Instant/SWIG).
103
The \texttt{jit} function returns a tuple
105
(compiled_form, compiled_module, form_data)
107
where \texttt{compiled\_form} is the compiled form (a Python wrapper
108
for \texttt{ufc::form}), \texttt{compiled\_module} is a Python module
109
containing the compiled form, finite elements, dof maps etc (a Python
110
wrapper for the complete set of generated code), and
111
\texttt{form\_data} is form metadata generated from the input form.
113
The JIT compiler caches generated modules such that if a Python script
114
including a call to the JIT compiler is run twice (in the same
115
directory) the Python module is only generated once. The generated
116
modules are stored in a cache directory defined by Instant. To clean
117
the cache, run the command \texttt{instant-clean}.
added
removed
doc/manual/chapters/python.tex
