FFC - the FEniCS Form Compiler
ffc [-h] [-V] [-S] [-v] [-s] [-e] [-l language] [-r
representation] [-f option] [-O] [-q quadrature-rule] ... input.ufl ...
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 system.
By default, FFC generates code according to the UFC specification
version 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/
- -h, --help
- Display help text and exit.
- -V, --version
- Display version number and exit.
- -S,
--signature
- Display UFC signature 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, -fprecompute_basis_const,
-fprecompute_ip_const, -fsimplify_expressions,
-feliminate_zeros, -fquadrature_degree=n and,
-fsplit, -fno_ferari, 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 versions.
- -f no-foo
- Don't generate code for UFC function with name 'foo'. Typical options
include -fno-evaluate_basis and
-fno-evaluate_basis_derivatives 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 efficiency 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 difference
that code will be generated to compute terms which are constant 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 element 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 regardless 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 automatically 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 compile-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
optimisation flags:
-fsimplify_expressions -feliminate_zeros
- -o directory,
--output-directory directory
- Specify the directory where the generated files should be written to. The
default output directory is the current ('.') directory.
- -q rule,
--quadrature-rule rule
- Specify the quadrature rule that should be used when integrating the
forms. This will affect both tensor and quadrature representation.
Currently, available options are 'default' and 'canonical'. The 'default'
option covers hand implemented quadrature rules for triangles and
tetrahedra with a degree of precision 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 'canonical' rule is too big for efficient computation, the option
-fquadrature_degree can be used.
Written by Anders Logg (logg@simula.no) with help from Kristian
Ølgaard, Marie Rognes, Garth N. Wells and many others.