NAME¶
FFC - the FEniCS Form Compiler
SYNOPSIS¶
ffc [-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 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/
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,
-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.
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.