FFC(1)

✨ FFC — the FEniCS Form Compiler ✨

okay bestie, gather round, because we're about to talk about ffc, aka the FEniCS Form Compiler, living its best life in the General Commands Manual, section 1. yes, section 1, the "actual command you type" section. she's a real one. 💅

NAME

FFC — the FEniCS Form Compiler. that's it, that's her name, and she's iconic. 🎀

SYNOPSIS

the vibe check, formally:

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

notice the ... on both ends? yeah, she takes many input files and she has many options. main character energy fr fr. ✨

DESCRIPTION

so what does she actually DO. she compiles multilinear forms into efficient low-level code. that's the whole point, that's the assignment, she ate.

here's the tea: the FEniCS Form Compiler FFC takes, as input, one or more files, and each of those files specifies one or more multilinear forms. then she compiles all those forms into efficient low-level code — code that's there for the automatic assembly of the tensors that represent the multilinear forms. 🧚

and the specific glow-up moment: FFC compiles a pair of bilinear and linear forms that define a variational problem into code you can use to efficiently assemble the corresponding linear system. like, that's the pipeline, that's the pipeline bestie.

by default, FFC generates code according to the UFC specification version 1.0 — that's Unified Form-assembly Code, hi, see http://www.fenics.org/ — but ngl you can control that by specifying a different output language (that's the -l option, we'll get there, be patient 🫶). and yes, you can even add new output languages to FFC. she's expandable, she's versatile, she's everything.

if you want the full description of FFC, including a whole specification of the form language used to define the multilinear forms, go read the FFC user manual, it's on the FEniCS web page: http://www.fenics.org/. the lore is deep, bestie. 📚

OPTIONS

okay this is the big section, hydrate first. 💧

• -h, --help — displays the help text and exits. she tells you about herself, and then she's gone. 💨
• -V, --version — displays the version number and exits. pop off, version number.
• -S, --signature — displays the UFC signature and exits. yes, a whole option just for flexing the signature.
• -v, --verbose — verbose mode, so more output gets printed. ⚠️ conflicts with -s. pick a lane, bestie, you can't do both.
• -s, --silent — silent mode, no output is printed. 🤫 conflicts with -v. again: pick. a. lane.
• -e, --error-control — error control mode! a set of additional forms that are useful for goal-oriented error control gets generated and compiled. fancy.
• -l language, --language language — specify the output language. it's one of 'ufc' (the default) or 'dolfin' (which is UFC with a small layer of DOLFIN-specific bindings on top). 🦋
• -r representation, --representation representation — specify the representation used for precomputation and code generation. one of 'quadrature' (default) or 'tensor'.
• -f option — specify code generation options. the list of available options depends on the language (format) you specified. 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 — all described in detail right below, don't worry, we're getting to every single one. 💖
• -f blas — generates code that uses BLAS to compute tensor products. heads up: this option is currently ignored, but it can be used to reduce the code size when the BLAS option is (re-)implemented in future versions. so like, she's a placeholder with aspirations. 🙈
• -f no-foo — don't generate code for the UFC function with the name 'foo'. typical options include -fno-evaluate_basis and -fno-evaluate_basis_derivatives, which reduce the size of the generated code when those functions aren't needed. no dead weight, periodt.
• -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 — an optimisation option for the quadrature representation. 🚨 this option is ignored if optimisation is not used (see the -O option), and it also implies the -fprecompute_ip_const option. it generates code that precomputes terms which are constant in the loops involving basis indices. this can reduce the operation count and thereby improve the runtime efficiency of the generated code. however — and this is the honest part — the improvements depend on the GCC compiler options as well as the characteristics of the variational form. so, ymmv, as always.
• -f precompute_ip_const — like the -fprecompute_basis_const option, with the only difference being that code gets generated to compute terms which are constant in the loops involving the integration points only.
• -f simplify_expressions — optimisation option for the quadrature representation. 🚨 again, ignored if optimisation is not used (see -O). before simplifying the expressions that compute the local element tensor, they get expanded in order to identify and precompute terms which are constant with respect to geometry and integration points. heads up though: this operation can be very expensive, because it involves creating many new terms, which might result in memory being exhausted. 😭 protect your RAM, bestie.
• -f eliminate_zeros — optimisation option for the quadrature representation. 🚨 also ignored if optimisation is not used (see -O). tables containing basis function values get compressed so they only contain non-zero values. this reduces 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 comes along with it. this optimisation option is usually most effective in combination with one of the other optimisation options. teamwork makes the dream work. 🫶
• -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 determines the degree automatically from the form.
• -f split — generate separate files for the declarations and the implementation. so organised. so demure.
• -f no_ferari — skip FErari optimizations, even if the -O flag is set. this only has effect when the tensor representation is used. you can combine this option with the -O flag to avoid potentially very long compilation times, by instructing FFC to only optimize when the quadrature representation is used. 🛑 protect your compile times too.
• -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 the -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. and for the quadrature representation, the -O option 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. the default output directory is the current ('.') directory. 🏠 home sweet home.
• -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 tries to use the 'default' option, since that typically results in the most efficient code being generated. if that's 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. and if the number of integration points used by the 'canonical' rule is too big for efficient computation, you can use the -fquadrature_degree option. 💅

BUGS

see https://fenicsproject.org/support/ for channels to send comments, questions, bug reports etc. she's not buggy, she's communicative. 🌸

AUTHOR

written by Anders Logg (logg@simula.no) with help from Kristian Ølgaard, Marie Rognes, Garth N. Wells and many others. shoutout to the whole squad, no cap. 👑

and that's the whole page, bestie!! 💜 she's FFC(1) from the General Commands Manual — go compile something gorgeous with her, you've got this. mwah. 🎀✨