FFC(1)FFC(1)NAME
FFC - the FEniCS Form Compiler
SYNOPSISffc [-h] [-V] [-v] [-s] [-e] [-l language] [-r representation] [-f
option] [-O] [-q quadrature-rule] ... input.ufl ...
DESCRIPTION
Compile multilinear forms into efficient low-level code.
The FEniCS Form Compiler FFC accepts as input one or more files, each
specifying one or more multilinear forms, and compiles the given forms
into efficient low-level code for automatic assembly of the tensors
representing the multilinear forms. In particular, FFC compiles a pair
of bilinear and linear forms defining a variational problem into code
that can be used to efficiently assemble the corresponding linear sys‐
tem.
By default, FFC generates code according to the UFC specification ver‐
sion 1.0 (Unified Form-assembly Code, see http://www.fenics.org/) but
this can be controlled by specifying a different output language
(option -l). It is also possible to add new output languages to FFC.
For a full description of FFC, including a specification of the form
language used to define the multilinear forms, see the FFC user manual
available on the FEniCS web page: http://www.fenics.org/
OPTIONS-h, --help
Display help text and exit.
-V, --version
Display version number and exit.
-v, --verbose
Verbose mode, more output is printed. Conflicts with -s.
-s, --silent
Silent mode, no output is printed. Conflicts with -v.
-e, --error-control
Error control mode, a set of additional forms useful for goal-
oriented error control is generated and compiled.
-l language, --language language
Specify output language, one of 'ufc' (default) or 'dolfin' (UFC
with a small layer of DOLFIN-specific bindings).
-r representation, --representation representation
Specify representation for precomputation and code generation,
one of 'quadrature' (default) or 'tensor'.
-f option
Specify code generation options. The list of options available
depends on the specified language (format). Current options
include -fblas, -fno-foo, -fprecision=n, -fprecom‐
pute_basis_const, -fprecompute_ip_const, -fsimplify_expressions,
-feliminate_zeros, -fquadrature_degree=n and, -fsplit, -fno_fer‐
ari, described in detail below.
-f blas
Generate code that uses BLAS to compute tensor products. This
option is currently ignored, but can be used to reduce the code
size when the BLAS option is (re-)implemented in future ver‐
sions.
-f no-foo
Don't generate code for UFC function with name 'foo'. Typical
options include -fno-evaluate_basis and -fno-evaluate_basis_de‐
rivatives to reduce the size of the generated code when these
functions are not needed.
-f precision=n
Set the number of significant digits to n in the generated code.
The default value of n is 15.
-f precompute_basis_const
Optimisation option for quadrature representation. This option
is ignored if optimisation is not used (see -O option), and it
also implies the -fprecompute_ip_const option. This option will
generate code that precompute terms which are constant in the
loops involving basis indices. This can result in a reduction
of the operation count and thereby improve the runtime effi‐
ciency of the generated code. However, the improvements depends
on the GCC compiler options as well as the characteristics of
the variational form.
-f precompute_ip_const
Like the -fprecompute_basis_const option with the only differ‐
ence that code will be generated to compute terms which are con‐
stant in the loops involving the integration points only.
-f simplify_expressions
Optimisation option for quadrature representation. This option
is ignored if optimisation is not used (see -O option). Before
simplifying the expressions to compute the local element tensor,
they are expanded in order to identify and precompute terms
which are constant with respect to geometry and integration
points. This operation can be very expensive since it involves
creating many new terms which might result in memory being
exhausted.
-f eliminate_zeros
Optimisation option for quadrature representation. This option
is ignored if optimisation is not used (see -O option). Tables
containing basis function values will be compressed such that
they only contain non zero values. This will reduce the loop
ranges and thereby the number of operations, but since a mapping
is introduced, in order to insert values correctly into the ele‐
ment matrix, some overhead is introduced. This optimisation
option is usually most effective in combination with one of the
other optimisation options.
-f quadrature_degree=n
Will generate a quadrature rule accurate up to degree n regard‐
less of the polynomial degree of the form. This option is only
valid for UFL forms and the specified degree will apply to ALL
terms of the given form for which no degree has been specified
through metadata! As default FFC will determine the degree auto‐
matically from the form.
-f split
Generate separate files for declarations and the implementation.
-f no_ferari
Skip FErari optimizations, even if the -O flag is set. This only
has effect when the tensor representation is used. This option
can be used in combination with the -O flag to avoid potentially
very long compilation times by instructing FFC to only optimize
when the quadrature representation is used.
-O, --optimize
Generate optimized code with a lower operation count compared to
non-optimized code for the assembly of the local element tensor.
This will in general increase the run-time performance of the
code. If the representation (see -r option) is 'tensor' then FFC
will use FErari optimizations. This option requires FErari and
should be used with caution since it may be very costly (at com‐
pile-time) for other than simple forms. If the representation
is 'quadrature' the compile-time increase tends to be much less
drastic compared to FErari for very complex forms. The -O option
for quadrature representation turns on the following optimisa‐
tion flags:
-fsimplify_expressions -feliminate_zeros
-o directory, --output-directory directory
Specify the directory where the generated files should be writ‐
ten to. The default output directory is the current ('.') direc‐
tory.
-q rule, --quadrature-rule rule
Specify the quadrature rule that should be used when integrating
the forms. This will affect both tensor and quadrature repre‐
sentation. Currently, available options are 'default' and
'canonical'. The 'default' option covers hand implemented quad‐
rature rules for triangles and tetrahedra with a degree of pre‐
cision less than or equal to six. The 'canonical' option relies
on FIAT to compute the quadrature rule which is based on the
Gauss--Legendre--Jacobi rule mapped onto simplices. By default,
FFC will try to use the 'default' option as this will typically
result in the most efficient code being generated. If this is
not possible (if the polynomial degree of the integrand is
larger than six, or if the cell is not one of 'triangle' or
'tetrahedron'), FFC will automatically apply the 'canonical'
rule. If the number of integration points used by the 'canoni‐
cal' rule is too big for efficient computation, the option
-fquadrature_degree can be used.
BUGS
Send comments, questions, bug reports etc. to ffc@lists.launchpad.net.
AUTHOR
Written by Anders Logg (logg@simula.no) with help from Kristian
Ølgaard, Marie Rognes, Garth N. Wells and many others.
FFC(1)
