1FFC(1)                      General Commands Manual                     FFC(1)
2
3
4

NAME

6       FFC - the FEniCS Form Compiler
7
8

SYNOPSIS

10       ffc [-h] [-V] [-S] [-v] [-s] [-e] [-l language] [-r representation] [-f
11       option] [-O] [-q quadrature-rule] ... input.ufl ...
12
13

DESCRIPTION

15       Compile multilinear forms into efficient low-level code.
16
17       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
25       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
30       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
34

OPTIONS

36       -h, --help
37              Display help text and exit.
38
39       -V, --version
40              Display version number and exit.
41
42       -S, --signature
43              Display UFC signature and exit.
44
45       -v, --verbose
46              Verbose mode, more output is printed. Conflicts with -s.
47
48       -s, --silent
49              Silent mode, no output is printed. Conflicts with -v.
50
51       -e, --error-control
52              Error  control  mode, a set of additional forms useful for goal-
53              oriented error control is generated and compiled.
54
55       -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
59       -r representation, --representation representation
60              Specify  representation  for precomputation and code generation,
61              one of 'quadrature' (default) or 'tensor'.
62
63       -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
71       -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
77       -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
83       -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
87       -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
98       -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
103       -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
113       -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
124       -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
132       -f split
133              Generate separate files for declarations and the implementation.
134
135       -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
142       -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
155              -fsimplify_expressions -feliminate_zeros
156
157
158       -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
163       -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
181
182
183       BUGS
184
185       See https://fenicsproject.org/support/ for channels to send comments,
186              questions, bug reports etc.
187
188

AUTHOR

190       Written  by  Anders  Logg  (logg@simula.no)  with  help  from  Kristian
191       Ølgaard, Marie Rognes, Garth N. Wells and many others.
192
193
194
195                                                                        FFC(1)
Impressum