Ubuntu Manpage: FFC - the FEniCS Form Compiler

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.

                                                                                           FFC(1)