1FFC(1) General Commands Manual FFC(1)
2
6 FFC - the FEniCS Form Compiler
7
10 ffc [-h] [-V] [-S] [-v] [-s] [-e] [-l language] [-r representation] [-f
11 option] [-O] [-q quadrature-rule] ... input.ufl ...
12
15 Compile multilinear forms into efficient low-level code.
16 The FEniCS Form Compiler FFC accepts as input one or more files, each
18 specifying one or more multilinear forms, and compiles the given forms
19 into efficient low-level code for automatic assembly of the tensors
20 representing the multilinear forms. In particular, FFC compiles a pair
21 of bilinear and linear forms defining a variational problem into code
22 that can be used to efficiently assemble the corresponding linear sys‐
23 tem.
24 By default, FFC generates code according to the UFC specification ver‐
26 sion 1.0 (Unified Form-assembly Code, see http://www.fenics.org/) but
27 this can be controlled by specifying a different output language
28 (option -l). It is also possible to add new output languages to FFC.
29 For a full description of FFC, including a specification of the form
31 language used to define the multilinear forms, see the FFC user manual
32 available on the FEniCS web page: http://www.fenics.org/
33
36 -h, --help
37 Display help text and exit.
38 -V, --version
40 Display version number and exit.
41 -S, --signature
43 Display UFC signature and exit.
44 -v, --verbose
46 Verbose mode, more output is printed. Conflicts with -s.
47 -s, --silent
49 Silent mode, no output is printed. Conflicts with -v.
50 -e, --error-control
52 Error control mode, a set of additional forms useful for goal-
53 oriented error control is generated and compiled.
54 -l language, --language language
56 Specify output language, one of 'ufc' (default) or 'dolfin' (UFC
57 with a small layer of DOLFIN-specific bindings).
58 -r representation, --representation representation
60 Specify representation for precomputation and code generation,
61 one of 'quadrature' (default) or 'tensor'.
62 -f option
64 Specify code generation options. The list of options available
65 depends on the specified language (format). Current options
66 include -fblas, -fno-foo, -fprecision=n, -fprecom‐
67 pute_basis_const, -fprecompute_ip_const, -fsimplify_expressions,
68 -feliminate_zeros, -fquadrature_degree=n and, -fsplit, -fno_fer‐
69 ari, described in detail below.
70 -f blas
72 Generate code that uses BLAS to compute tensor products. This
73 option is currently ignored, but can be used to reduce the code
74 size when the BLAS option is (re-)implemented in future ver‐
75 sions.
76 -f no-foo
78 Don't generate code for UFC function with name 'foo'. Typical
79 options include -fno-evaluate_basis and -fno-evaluate_basis_de‐
80 rivatives to reduce the size of the generated code when these
81 functions are not needed.
82 -f precision=n
84 Set the number of significant digits to n in the generated code.
85 The default value of n is 15.
86 -f precompute_basis_const
88 Optimisation option for quadrature representation. This option
89 is ignored if optimisation is not used (see -O option), and it
90 also implies the -fprecompute_ip_const option. This option will
91 generate code that precompute terms which are constant in the
92 loops involving basis indices. This can result in a reduction
93 of the operation count and thereby improve the runtime effi‐
94 ciency of the generated code. However, the improvements depends
95 on the GCC compiler options as well as the characteristics of
96 the variational form.
97 -f precompute_ip_const
99 Like the -fprecompute_basis_const option with the only differ‐
100 ence that code will be generated to compute terms which are con‐
101 stant in the loops involving the integration points only.
102 -f simplify_expressions
104 Optimisation option for quadrature representation. This option
105 is ignored if optimisation is not used (see -O option). Before
106 simplifying the expressions to compute the local element tensor,
107 they are expanded in order to identify and precompute terms
108 which are constant with respect to geometry and integration
109 points. This operation can be very expensive since it involves
110 creating many new terms which might result in memory being
111 exhausted.
112 -f eliminate_zeros
114 Optimisation option for quadrature representation. This option
115 is ignored if optimisation is not used (see -O option). Tables
116 containing basis function values will be compressed such that
117 they only contain non zero values. This will reduce the loop
118 ranges and thereby the number of operations, but since a mapping
119 is introduced, in order to insert values correctly into the ele‐
120 ment matrix, some overhead is introduced. This optimisation
121 option is usually most effective in combination with one of the
122 other optimisation options.
123 -f quadrature_degree=n
125 Will generate a quadrature rule accurate up to degree n regard‐
126 less of the polynomial degree of the form. This option is only
127 valid for UFL forms and the specified degree will apply to ALL
128 terms of the given form for which no degree has been specified
129 through metadata! As default FFC will determine the degree auto‐
130 matically from the form.
131 -f split
133 Generate separate files for declarations and the implementation.
134 -f no_ferari
136 Skip FErari optimizations, even if the -O flag is set. This only
137 has effect when the tensor representation is used. This option
138 can be used in combination with the -O flag to avoid potentially
139 very long compilation times by instructing FFC to only optimize
140 when the quadrature representation is used.
141 -O, --optimize
143 Generate optimized code with a lower operation count compared to
144 non-optimized code for the assembly of the local element tensor.
145 This will in general increase the run-time performance of the
146 code. If the representation (see -r option) is 'tensor' then FFC
147 will use FErari optimizations. This option requires FErari and
148 should be used with caution since it may be very costly (at com‐
149 pile-time) for other than simple forms. If the representation
150 is 'quadrature' the compile-time increase tends to be much less
151 drastic compared to FErari for very complex forms. The -O option
152 for quadrature representation turns on the following optimisa‐
153 tion flags:
154 -fsimplify_expressions -feliminate_zeros
156 -o directory, --output-directory directory
159 Specify the directory where the generated files should be writ‐
160 ten to. The default output directory is the current ('.') direc‐
161 tory.
162 -q rule, --quadrature-rule rule
164 Specify the quadrature rule that should be used when integrating
165 the forms. This will affect both tensor and quadrature repre‐
166 sentation. Currently, available options are 'default' and
167 'canonical'. The 'default' option covers hand implemented quad‐
168 rature rules for triangles and tetrahedra with a degree of pre‐
169 cision less than or equal to six. The 'canonical' option relies
170 on FIAT to compute the quadrature rule which is based on the
171 Gauss--Legendre--Jacobi rule mapped onto simplices. By default,
172 FFC will try to use the 'default' option as this will typically
173 result in the most efficient code being generated. If this is
174 not possible (if the polynomial degree of the integrand is
175 larger than six, or if the cell is not one of 'triangle' or
176 'tetrahedron'), FFC will automatically apply the 'canonical'
177 rule. If the number of integration points used by the 'canoni‐
178 cal' rule is too big for efficient computation, the option
179 -fquadrature_degree can be used.
180 BUGS
184 See https://fenicsproject.org/support/ for channels to send comments,
186 questions, bug reports etc.
187
190 Written by Anders Logg (logg@simula.no) with help from Kristian
191 Ølgaard, Marie Rognes, Garth N. Wells and many others.
192 FFC(1)