Source-linked AI summary
Unified Form Language: A domain-specific language for weak formulations of partial differential equations
Martin S. Alnaes, Anders Logg, Kristian B. Oelgaard, Marie E. Rognes, Garth N. Wells
TL;DR
UFL addresses the need for a language that represents weak PDE formulations for numerical approximation. It provides composable mathematical abstractions and generates representations for downstream compilers, and it has supported advanced finite element algorithms in FEniCS, especially for coupled systems and automatically differentiated problems.
Problem
Weak PDE formulations require a readable, expressive representation that supports complex finite element problems and numerical approximation.
Method
UFL is an embedded Python domain-specific language that represents variational PDE statements as abstract expressions for form compilers and downstream problem-solving environments.
Results
UFL has enabled advanced automated finite element algorithms in FEniCS, particularly for complicated coupled systems and problems where automatic differentiation reduces application-development burden.
Takeaways & Limitations
UFL provides a compact, readable, and extensible interface for specifying variational PDE mathematics within software pipelines.
Takeaways & Limitations
UFL does not model geometrical domains; users or problem-solving environments must associate indexed subdomain integrals with concrete geometric representations.
Abstract
from arXiv · showhide
We present the Unified Form Language (UFL), which is a domain-specific language for representing weak formulations of partial differential equations with a view to numerical approximation. Features of UFL include support for variational forms and functionals, automatic differentiation of forms and expressions, arbitrary function space hierarchies for multi-field problems, general differential operators and flexible tensor algebra. With these features, UFL has been used to effortlessly express finite element methods for complex systems of partial differential equations in near-mathematical notation, resulting in compact, intuitive and readable programs. We present in this work the language and its construction. An implementation of UFL is freely available as an open-source software library. The library generates abstract syntax tree representations of variational problems, which are used by other software libraries to generate concrete low-level implementations. Some application examples are presented and libraries that support UFL are highlighted.
1. INTRODUCTION
UFL is introduced as a near-mathematical language for expressing variational PDE forms. It provides expressive abstractions and generates representations that form compilers and problem-solving environments can turn into executable implementations.
- UFL expresses variational forms of partial differential equations in near-mathematical notation.
- Its operations support compact, expressive input whose complexity is comparable to classical mathematical presentations.
- UFL offers abstract building blocks, a mostly dimension-independent interface, and support for arbitrarily many coupled fields.
- UFL generates abstract problem representations rather than solving problems directly, allowing form compilers to produce concrete low-level implementations.
- Generated code can be used by environments such as DOLFIN to assemble and solve systems from finite element discretizations described in UFL.
- UFL is implemented as an embedded domain-specific language in Python, combining composable expression types, operators, and algorithms.
2. MATHEMATICAL CONCEPTS AND SCOPE
UFL formalizes variational PDE forms as integrals over cells and facets, with multilinear arguments, coefficient functions, tensor notation, and differentiation. Its scope stops at abstract problem representation: concrete subdomains and implementations are supplied externally.
- Scope and abstractions: UFL assumes variational PDE formulations are sums of integrals whose expressions combine functions, geometric quantities, differential operators, and tensor algebra.The paper assumes familiarity with variational formulations and finite element methods.
- Variational forms: A form is linear in each argument space and may be nonlinear in coefficient functions; arity 0, 1, and 2 correspond to functionals, linear forms, and bilinear forms.Assembly produces a scalar, vector, or matrix for these three arities, respectively.
- Differentiation: UFL differentiation uses Gâteaux derivatives to transform forms into higher-arity forms, assuming integration domains do not depend on the differentiation variable.This supports applications such as minimization problems and Jacobian computation for nonlinear forms.
- Tensors and tensor algebra: UFL supports tensor shapes, components, multi-indices, implicit summation over repeated free indices, and tensor-valued functions with compact index notation.Scalars, vectors, and higher-rank tensors are represented through their shapes and basis components.
- Finite element spaces: Nested mixed finite element hierarchies of arbitrary finite depth are admitted when mixed elements extend the global finite element construction.This provides the stated hierarchy generalization for mixed spaces.
3. OVERVIEW OF THE LANGUAGE
UFL is organized as declarative sublanguages for finite elements, expressions, and forms rather than as an imperative programming environment.
- Language organization: UFL has a declarative character: it omits side effects, statement sequences, subroutines, and explicit loops found in imperative languages.Inline conditional expressions are its only branching instructions.
3.1. Finite elements
UFL provides abstractions for constructing local finite element spaces, including primitive, mixed, enriched, and restricted elements, with mathematical operators for readable composition.
- Finite element abstractions: UFL defines primitive, mixed, enriched, and restricted finite element abstractions, each carrying value shape, cell, and embedding polynomial degree information.UFL focuses on local finite element-space properties rather than global continuity or degrees-of-freedom implementations.
- Primitive elements: Primitive finite elements are specified by a family, cell, polynomial degree, and optionally a quadrature scheme.Family aliases accommodate multiple literature names and finite element exterior calculus notation.
- Structured elements: Vector and tensor elements extend finite element definitions with structured value shapes and, for tensor elements, higher-dimensional rank-two structure.Vector elements can also be built from vector-valued corresponding elements.
- Mixed elements: Mixed elements combine finite, vector, tensor, or nested mixed subelements over the same cell, allowing finite-depth nested hierarchies.The mixed-element degree is determined by the maximal degree of its subelements.
- Enriched and restricted elements: Enriched elements combine subelements sharing a cell and value shape, while restricted elements eliminate functions that vanish on selected cells or facets.Restricted elements can target cell facets for specialized discretizations.
- Operators: UFL overloads multiplication, addition, and indexing operators over finite elements, pairing concise usage with equivalent verbose syntax.Table II presents these operator forms and their expanded equivalents.
3.2. Expressions
UFL represents expressions as typed, immutable symbolic objects supporting tensor shapes, free indices, terminal data, indexing, algebra, nonlinear functions, and differentiation-related operations.
- Expression representation: Each UFL expression is an object in an expression tree, with operator results uniquely determined by their operator type and operand expressions.Terminal expressions carry data such as finite elements, geometry, or values.
- Expression representation: Immutable expression state enables subexpression reuse by reference rather than copying, which is critical for efficient symbolic implementation.Python variables may store reusable subexpression references, although UFL has no mutable variables.
- Expression representation: Expression evaluation generally requires values for its non-literal terminal dependencies; direct symbolic evaluation is expensive and unsuitable for large-scale computation.Expressions with empty dependency sets can be evaluated symbolically.
- Tensor structure: Every expression has a defined tensor shape and free-index set, which are distinct software properties even when mathematically related.Indexing can turn a rank-two tensor component into a scalar-valued expression carrying free indices.
- Terminal expressions: Terminal expressions include literal constants, geometric quantities, and functions whose tensor properties derive from their function spaces.Geometric quantities include coordinates, facet normals, areas, volumes, and circumradii; some are restricted to facets.
- Operators and notation: UFL supports conventional index notation, component-wise indexing, tensor construction, arithmetic, tensor products, implicit summation, and nonlinear scalar or element-wise functions.Operators impose shape and free-index compatibility, while dot contracts tensor axes and inner applies to tensors of equal shape.
3.3. Integrals and variational forms
UFL builds integrals and variational forms from symbolic integrands and measures, then provides form-level transformations including extraction, replacement, adjoints, and automatic differentiation.
- 3.3. Integrals and variational forms: UFL represents variational problems as sums of integrals over geometric domains, with integrands formed from functions, geometric quantities, and operators.The framework assumes variational formulations expressed as sums of integrals over geometric domains.
- 3.3. Integrals and variational forms: A UFL measure combines a domain type, domain identifier, and optional metadata, supporting cell, exterior-facet, and interior-facet integration.The domain identifier is a non-negative integer.
- 3.3.1. Integrals and forms: Multiplying an expression by a measure creates an integral; interior-facet integrands must use appropriate restrictions and may depend on argument functions.The measure supplies the integration domain while the expression supplies the integrand.
- 3.3.1. Integrals and forms: A form is a sum of one or more integrals, classified by arity as a functional, linear form, or bilinear form for arities 0, 1, or 2.The number of coefficient functions does not affect form arity.
- 3.3.2. Form operators: Form algorithms generate new forms for extracting terms, replacing functions, applying actions, and computing adjoints.lhs, rhs, and system extract arity-specific terms from variational equations.
- 3.3.2. Form operators: The derivative operator provides Gâteaux differentiation with respect to individual or multiple coefficients, including derivatives that become linear forms on mixed spaces.This supports separate and simultaneous coefficient variations.
- 3.3.2. Form operators: High-level form operations enable algorithms to be expressed at a higher abstraction level than traditional implementations.The paper points to concrete examples using UFL and operations on forms.
3.4. The .ufl file format
The .ufl format lets users define UFL forms in Python syntax for offline compilation or integration with Python and compiled-language problem-solving environments.
- 3.4. The .ufl file format: UFL can be integrated directly into Python environments or written in .ufl files compiled offline for environments such as C++.A .ufl file is interpreted by Python with the full UFL namespace imported, after which forms and elements are extracted from the namespace.
4. EXAMPLES
The examples show UFL specifications for standard and mixed finite element discretizations, discontinuous Galerkin methods, Stokes flow, and nonlinear hyperelasticity, including automatic variational differentiation.
- Examples: The examples are chosen to illustrate UFL features, with benefits expected to be greatest for complicated, non-standard equations.The paper emphasizes that UFL is not limited to simple equations.
- 4.1. Poisson equation: The Poisson examples cover H1-conforming, L2-conforming discontinuous Galerkin/interior-penalty, and mixed H(div)/L2-conforming discretizations.The standard H1 formulation uses continuous piecewise polynomial trial and test spaces.
- 4.1.1. H1-conforming discretization: The H1 Poisson formulation is specified compactly with trial and test functions, coefficient fields, gradient inner products, and cell and boundary measures.The supplied UFL code defines bilinear and linear forms using kappa, f, g, dx, and ds.
- 4.1.2. L2-conforming discretization: The L2 discretization uses discontinuous Galerkin operators for jumps and averages, producing a notably more complex expression tree than the H1 formulation.The implementation uses jump() and avg(), while Figures 2 and 3 illustrate the resulting tree.
- 4.1.3. H(div)/L2-conforming discretization: The mixed Poisson formulation replaces the second-order equation with a first-order system and uses BDM and discontinuous piecewise-constant spaces.A direct discretization with continuous piecewise linear elements is unstable; the Dirichlet condition is natural and the Neumann condition essential.
- 4.2. Stokes equations: The Stokes example uses an inf-sup stable [P2]d–P1 Taylor–Hood discretization for velocity and pressure after integration by parts.The mixed variational problem uses test functions for the momentum and incompressibility equations.
- 4.3. Neo-Hookean hyperelastic model: The hyperelastic example formulates a compressible neo-Hookean problem by minimizing potential energy, with deformation quantities defined from the displacement gradient.Newton’s method uses the first Gâteaux derivative for the residual and the second for the Jacobian.
5. REPRESENTATION OF EXPRESSIONS
UFL represents expressions as typed symbolic objects organized in dependency DAGs, integrating tensor shapes, indices, operators, and conservative simplification for downstream form compilation.
- Expression model: Terminal expressions include multi-indices, literals, geometric quantities, coefficient functions, and argument functions.
- Operators: Operator categories cover indexing, arithmetic, nonlinear scalar functions, tensor algebra, differential operators, restrictions, Boolean operations, and conditionals.Conditional expressions provide the only explicit branching instruction besides restrictions.
- Expression model: UFL expressions are terminals or operators applied recursively to other expressions, forming a typed directed acyclic graph of dependencies.Each vertex represents an expression and carries a terminal or operator type.
- Tensor and index structure: UFL treats shapes and indices as integral to every expression, with dedicated representations for indexed expressions and mappings between index and tensor notation.Form compilers can reduce the resulting representation complexity during translation.
- Tensor and index structure: Implicit summation is converted early into explicit IndexSum nodes, allowing most symbolic algorithms to avoid special handling of implicit summation rules.For example, u[i]*v[i] is represented as an IndexSum over the repeated index.
- Simplification: UFL uses conservative simplification so authored expressions remain recognizable while selected rewrites can limit symbolic expression growth.This design reflects UFL’s role as a front end for multiple form compilers.
6. ALGORITHMS
UFL supplies reusable algorithms for traversing, evaluating, transforming, and rebuilding expression DAGs, with traversal behavior adapted to operator-specific evaluation contexts.
- Algorithm framework: UFL provides algorithms for analyzing and transforming expressions, with particular emphasis on differentiation.
- Evaluation: Expression DAGs use terminal and non-terminal vertices in topological order, ensuring dependencies precede the expressions that depend on them.
- Evaluation: Evaluation separates terminal and operator handlers and can produce numerical values, symbolic expressions, or generated source-code strings.
- Context-sensitive evaluation: Operators that provide evaluation context require algorithm-specific handling because operand rules may depend on differentiation variables or restriction sides.
- Evaluation: Recursive evaluation can use post-order traversal, while context-sensitive evaluation mixes post-order and pre-order traversal as needed.A topologically ordered loop avoids visiting a shared vertex twice in the list-based representation.
- Transformation: Dynamic multifunctions and visitor-based transformers dispatch type-specific rules for recursive numerical evaluation and expression transformation.
- Transformation: ReuseTransformer-based algorithms rebuild only modified portions of immutable expressions and reuse unchanged subexpressions.This supports compact implementations such as partial evaluation and terminal replacement.
7. VALIDATION
UFL validates expressions during operator application and combines defensive testing with mathematical identities to detect symbolic, numerical, and evaluation errors.
- Expression validation: Operators validate operand shapes and free-index consistency, catching common indexing errors when expressions are constructed.Additional checks include restrictions on facet integrals.
- Testing strategy: UFL testing uses assertions, unit tests, integration tests in other FEniCS components, and static code analysis.
- Testing strategy: Numerical evaluations of symbolic derivatives can be compared with manually derived derivatives or reference values.
- Mathematical validation: Green’s theorem identities enable combined tests of symbolic differentiation, numerical differentiation, symbolic evaluation, and higher-order derivatives.Setting v = grad f provides a higher-order derivative test.
- Practical validation: The FEniCS software stack adds debugging complexity, while UFL’s automated validation checks consistency and catches user errors at multiple abstraction levels.UFL had also been tested in active FEniCS use for more than three years.
8. CONCLUSIONS
The paper presents UFL as a compact, readable, and efficient language for variational PDE expressions, with sustained use in the FEniCS pipeline and extensions beyond its core implementation.
- Conclusions: UFL and its algorithms support compact, readable, and efficient specification of mathematical expressions for variational PDE formulations.
- Conclusions: The paper provides both high-level and detailed views intended to support practical use, implementation understanding, and further development.
- Impact and extensions: UFL has been extensively used in the FEniCS software pipeline since 2009.
- Impact and extensions: In FEniCS, UFL has been crucial for advanced automated finite element algorithms, especially coupled systems and problems where automatic differentiation reduces developer burden.
- Impact and extensions: UFL has been extended to extended finite element methods and code generation for different architectures beyond its core implementation.