DOLFIN User Manual

February 24, 2006

Hoffman, Jansson, Logg, Wells

www.fenics.org
Visit http://www.fenics.org/ for the latest version of this manual.
Send comments and suggestions to [email protected].
Contents

About this manual 9

1 Introduction 13

1.1 The FEniCS project . . . . . . . . . . . . . . . . . . . . . . . 13

1.2 The finite element method . . . . . . . . . . . . . . . . . . . . 13

1.3 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

2 Quickstart 15

2.1 Downloading and installing DOLFIN . . . . . . . . . . . . . . 15

2.2 Solving Poisson’s equation with DOLFIN . . . . . . . . . . . . 16

2.2.1 Setting up the variational problem . . . . . . . . . . . 17

2.2.2 Writing the solver . . . . . . . . . . . . . . . . . . . . . 18

2.2.3 Compiling the program . . . . . . . . . . . . . . . . . . 21

2.2.4 Running the program . . . . . . . . . . . . . . . . . . . 22

2.2.5 Visualizing the solution . . . . . . . . . . . . . . . . . . 23

3
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

3 Linear algebra 25

3.1 Matrices and vectors . . . . . . . . . . . . . . . . . . . . . . . 25

3.2 Matrix-free matrices . . . . . . . . . . . . . . . . . . . . . . . 26

3.3 Linear solvers . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

3.4 Preconditioning . . . . . . . . . . . . . . . . . . . . . . . . . . 27

4 The mesh 29

4.1 Mesh iterators . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

4.2 Mesh refinement . . . . . . . . . . . . . . . . . . . . . . . . . . 31

5 Functions 33

5.1 Basic properties . . . . . . . . . . . . . . . . . . . . . . . . . . 33

5.1.1 Representation . . . . . . . . . . . . . . . . . . . . . . 34

5.1.2 Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . 34

5.1.3 Assignment . . . . . . . . . . . . . . . . . . . . . . . . 35

5.1.4 Components and sub functions . . . . . . . . . . . . . 35

5.1.5 Output . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

5.2 Discrete functions . . . . . . . . . . . . . . . . . . . . . . . . . 36

5.2.1 Creating a discrete function . . . . . . . . . . . . . . . 37

5.2.2 Accessing discrete function data . . . . . . . . . . . . . 38

5.2.3 Attaching discrete function data . . . . . . . . . . . . . 38

5.3 User-defined functions . . . . . . . . . . . . . . . . . . . . . . 39

4
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

5.3.1 Creating a sub class . . . . . . . . . . . . . . . . . . . 39

5.3.2 Specifying a function-pointer . . . . . . . . . . . . . . . 41

5.3.3 Cell-dependent functions . . . . . . . . . . . . . . . . . 41

5.4 Time-dependent functions . . . . . . . . . . . . . . . . . . . . 42

6 Ordinary differential equations 43

7 Partial differential equations 45

7.1 Boundary value problems . . . . . . . . . . . . . . . . . . . . . 45

7.2 Variational formulation . . . . . . . . . . . . . . . . . . . . . . 46

7.3 Finite elements and FIAT . . . . . . . . . . . . . . . . . . . . 46

7.4 Compiling the variational form with FFC . . . . . . . . . . . . 47

7.5 Element matrices and vectors . . . . . . . . . . . . . . . . . . 47

7.6 Assemble matrices and vectors . . . . . . . . . . . . . . . . . . 48

7.7 Specifying boundary conditions and data . . . . . . . . . . . . 49

7.8 Initial value problems . . . . . . . . . . . . . . . . . . . . . . . 50

8 Nonlinear solver 53

8.1 Nonlinear functions . . . . . . . . . . . . . . . . . . . . . . . . 53

8.2 Newton solver . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

8.2.1 Linear solver . . . . . . . . . . . . . . . . . . . . . . . 55

8.2.2 Application of Dirichlet boundary conditions . . . . . . 55

5
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

8.2.3 Newton solver parameters . . . . . . . . . . . . . . . . 55

8.2.4 Application of Dirichlet boundary conditions . . . . . . 55

8.3 Incremental Newton solver . . . . . . . . . . . . . . . . . . . . 55

9 Input/output 57

9.1 Files and objects . . . . . . . . . . . . . . . . . . . . . . . . . 57

9.2 File formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

9.2.1 DOLFIN XML . . . . . . . . . . . . . . . . . . . . . . 59

9.2.2 VTK . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

9.2.3 OpenDX . . . . . . . . . . . . . . . . . . . . . . . . . . 61

9.2.4 GNU Octave . . . . . . . . . . . . . . . . . . . . . . . 61

9.2.5 MATLAB . . . . . . . . . . . . . . . . . . . . . . . . . 62

9.2.6 Tecplot . . . . . . . . . . . . . . . . . . . . . . . . . . 62

9.2.7 GiD . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

9.3 Converting between file formats . . . . . . . . . . . . . . . . . 63

9.4 A note on new file formats . . . . . . . . . . . . . . . . . . . . 63

10 The log system 65

10.1 Generating log messages . . . . . . . . . . . . . . . . . . . . . 65

10.2 Warnings and errors . . . . . . . . . . . . . . . . . . . . . . . 66

10.3 Debug messages and assertions . . . . . . . . . . . . . . . . . 67

10.4 Task notification . . . . . . . . . . . . . . . . . . . . . . . . . 68

6
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

10.5 Progress bars . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

10.6 Controlling the destination of output . . . . . . . . . . . . . . 70

11 The parameter system 73

11.1 Retrieving the value of a parameter . . . . . . . . . . . . . . . 73

11.2 Modifying the value of a parameter . . . . . . . . . . . . . . . 74

11.3 Adding a new parameter . . . . . . . . . . . . . . . . . . . . . 75

11.4 Saving parameters to file . . . . . . . . . . . . . . . . . . . . . 76

11.5 Loading parameters from file . . . . . . . . . . . . . . . . . . . 76

12 Solvers 77

12.1 Poisson’s equation . . . . . . . . . . . . . . . . . . . . . . . . 78

12.1.1 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

12.1.2 Performance . . . . . . . . . . . . . . . . . . . . . . . . 79

12.1.3 Limitations . . . . . . . . . . . . . . . . . . . . . . . . 79

12.2 Convection–diffusion . . . . . . . . . . . . . . . . . . . . . . . 80

12.2.1 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

12.2.2 Performance . . . . . . . . . . . . . . . . . . . . . . . . 81

12.2.3 Limitations . . . . . . . . . . . . . . . . . . . . . . . . 81

12.3 Incompressible Navier–Stokes . . . . . . . . . . . . . . . . . . 82

12.3.1 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

12.3.2 Performance . . . . . . . . . . . . . . . . . . . . . . . . 82

7
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

12.3.3 Limitations . . . . . . . . . . . . . . . . . . . . . . . . 82

12.4 Elasticity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

12.4.1 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

12.4.2 Performance . . . . . . . . . . . . . . . . . . . . . . . . 83

12.4.3 Limitations . . . . . . . . . . . . . . . . . . . . . . . . 83

A Reference elements 87

A.1 The reference triangle . . . . . . . . . . . . . . . . . . . . . . . 87

A.2 The reference tetrahedron . . . . . . . . . . . . . . . . . . . . 89

A.3 Ordering of degrees of freedom . . . . . . . . . . . . . . . . . . 90

A.3.1 Mesh entities . . . . . . . . . . . . . . . . . . . . . . . 90

A.3.2 Ordering among mesh entities . . . . . . . . . . . . . . 93

A.3.3 Internal ordering on edges . . . . . . . . . . . . . . . . 93

A.3.4 Alignment of edges . . . . . . . . . . . . . . . . . . . . 94

A.3.5 Internal ordering on faces . . . . . . . . . . . . . . . . 94

A.3.6 Alignment of faces . . . . . . . . . . . . . . . . . . . . 94

B Installation 97

B.1 Installing from source . . . . . . . . . . . . . . . . . . . . . . . 97

B.1.1 Dependencies and requirements . . . . . . . . . . . . . 97

B.1.2 Downloading the source code . . . . . . . . . . . . . . 99

B.1.3 Compiling the source code . . . . . . . . . . . . . . . . 100

8
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

B.1.4 Compiling the demo programs . . . . . . . . . . . . . . 102

B.1.5 Compiling a program against DOLFIN . . . . . . . . . 102

B.2 Debian package . . . . . . . . . . . . . . . . . . . . . . . . . . 103

B.3 Installing from source under Windows . . . . . . . . . . . . . . 103

C Contributing code 105

C.1 Creating a patch . . . . . . . . . . . . . . . . . . . . . . . . . 105

C.2 Sending patches . . . . . . . . . . . . . . . . . . . . . . . . . . 107

C.3 Applying a patch (maintainers) . . . . . . . . . . . . . . . . . 107

C.4 License agreement . . . . . . . . . . . . . . . . . . . . . . . . . 108

D License 109

9
About this manual

This manual is currently being written. As a consequence, some sections

may be incomplete or inaccurate.

Intended audience

This manual is written both for the beginning and the advanced user. There
is also some useful information for developers. More advanced topics are
treated at the end of the manual or in the appendix.

Typographic conventions

• Code is written in monospace (typewriter) like this.

• Commands that should be entered in a Unix shell are displayed as

follows:

# ./configure
# make

Commands are written in the dialect of the bash shell. For other shells,
such as tcsh, appropriate translations may be needed.

11
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

Enumeration and list indices

Throughout this manual, elements xi of sets {xi } of size n are enumerated

from i = 0 to i = n − 1. Derivatives in Rn are enumerated similarly:
∂
, ∂ , . . . , ∂x∂n−1 .
∂x0 ∂x1

Contact

Comments, corrections and contributions to this manual are most welcome

and should be sent to

[email protected]

12
Chapter 1

Introduction

I Developer’s note: This chapter is currently being written. . .

1.1 The FEniCS project

1.2 The finite element method

1.3 Overview

DOLFIN is implemented as a C++ library and can be used either as a stand-

alone solver, or as a tool for the development and implementation of new
methods. To simplify usage and emphasize structure, DOLFIN is organized
into three levels of abstraction, referred to as kernel level, module level, and
user level, as shown in Figure 1.1. Core features, such as the automatic eval-
uation of variational forms and adaptive mesh refinement, are implemented
as basic tools at kernel level. At module level, new solvers/modules can be
assembled from these basic tools and integrated into the system. At user
level, a model of the form is specified and solved, either using one of the
built-in solvers/modules or by direct usage of the basic tools.

13
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

Figure 1.1: Simplified component diagram of DOLFIN.

14
Chapter 2

Quickstart

This chapter demonstrates how to get started with DOLFIN, including down-
loading and installing the latest version of DOLFIN, and solving Poisson’s
equation. These topics are discussed in more detail elsewhere in this manual.
In particular, see Appendix B for detailed installation instructions and Chap-
ter 7 for a detailed discussion of how to solve partial differential equations
with DOLFIN.

2.1 Downloading and installing DOLFIN

The latest version of DOLFIN can be found on the FEniCS web page:

http://www.fenics.org/

The following commands illustrate the installation process, assuming that

you have downloaded release 0.1.0 of DOLFIN:

# tar zxfv dolfin-0.1.0.tar.gz

# cd dolfin-0.1.0

15
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

# ./configure
# make
# make install

Make sure that you download the latest release (which is not 0.1.0).

Note that you may need to be root on your system to perform the last
step. Since DOLFIN depends on a number of other packages, including the
linear algebra package PETSc and the form compiler FFC, you may also need
download and install these packages before you can compile DOLFIN. (See
Appendix B for detailed instructions.)

2.2 Solving Poisson’s equation with DOLFIN

Let’s say that we want to solve Poisson’s equation on the unit square Ω =
(0, 1)×(0, 1) with homogeneous Dirichlet boundary conditions on the bound-
ary Γ0 = {(x, y) ∈ ∂Ω : x = 1}, homogeneous Neumann boundary condi-
tions on the remaining part of the boundary and right-hand side given by
f = x sin(y),

− ∆u(x, y) = x sin(y), x ∈ Ω = (0, 1) × (0, 1), (2.1)

u(x) = 0, x ∈ Γ0 = {(x, y) ∈ ∂Ω : x = 1}, (2.2)
∂n u(x) = 0, x ∈ ∂Ω \ Γ0 . (2.3)

To solve a partial differential equation such as Poisson with DOLFIN, it

must first be rewritten in variational form. The discrete variational (finite
element) formulation for Poisson’s equation reads: Find u ∈ Vh such that

a(v, U ) = L(v) ∀v ∈ V̂h , (2.4)

with (V̂h , Vh ) a pair of suitable function spaces (the test and trial spaces).
The bilinear form a : V̂h × Vh → R is given by
Z
a(v, U ) = ∇v · ∇U dx (2.5)
Ω

16
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

and the linear form L : V̂ → R is given by

Z
L(v) = v f dx. (2.6)
Ω

2.2.1 Setting up the variational problem

The variational problem (2.4) must be given to DOLFIN as a pair of bilin-

ear and linear forms (a, L) using the form compiler FFC. This is done by
entering the definition of the forms in a text file with extension .form, e.g.
Poisson.form, as follows:

element = FiniteElement(‘‘Lagrange’’, ‘‘triangle’’, 1)

v = BasisFunction(element)
U = BasisFunction(element)
f = Function(element)

a = dot(grad(v), grad(U))*dx
L = v*f*dx

The example is given here for piecewise linear finite elements in two dimen-
sions, but other choices are available, including arbitrary order Lagrange
elements in two and three dimensions.

To compile the pair of forms (a, L), now call the form compiler on the
command-line as follows:

# ffc Poisson.form

This generates the file Poisson.h which implements the forms in C++ for
inclusion in your DOLFIN program.

17
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

2.2.2 Writing the solver

Having compiled the variational problem (2.4) with FFC, it is now easy to
implement a solver for Poisson’s equation. We first discuss the implementa-
tion line by line and then present the complete program. The source code
for this example is available in the directory src/demo/pde/poisson/ of the
DOLFIN source tree.

At the beginning of our C++ program, which we write in a text file named
main.cpp, we must first include the header file dolfin.h, which gives our
program access to the DOLFIN class library. In addition, we include the
header file Poisson.h generated by the form compiler. Since all classes in
the DOLFIN class library are defined within the namespace dolfin, we also
specify that we want to work within this namespace:

#include <dolfin.h>
#include ‘‘Poisson.h’’

using namespace dolfin;

Since we are writing a C++ program, we need to create a main function.

You are free to organize your program any way you like, but in this simple
example we just write our program inside the main function:

int main()
{
// Write your program here
return 0;
}

We now proceed to specify the right-hand side f of (2.1). This is done by

defining a new subclass of Function and overloading the eval() function to
return the value f (x, y) = x sin(y):

18
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

class : public Function

{
real eval(const Point& p, unsigned int i)
{
return p.x*sin(p.y);
}
} f;

The boundary condition is specified similarly, by overloading the eval()

function for a subclass of BoundaryCondition:

class : public BoundaryCondition

{
void eval(BoundaryValue& value, const Point& p, unsigned int i)
{
if ( std::abs(p.x - 1.0) < DOLFIN_EPS )
value = 0.0;
}
} bc;

We only need to specify the boundary condition explicitly on the Dirich-

let boundary. On the remaining part of the boundary, DOLFIN assumes
homogeneous Neumann boundary conditions by default.

Note that there is currently no easy way to impose non-homogeneous Neu-

mann boundary conditions or other combinations of boundary conditions.
This will most certainly be added to a future release of DOLFIN.

Next, we need to create a mesh. DOLFIN relies on external programs for

mesh generation, and imports meshes in DOLFIN XML format. However,
for simple domains like the unit square or unit cube, DOLFIN provides a
built-in mesh generator. To generate a uniform mesh of the unit square with
mesh size 1/16 (with a total of 2 · 162 = 512 triangles), we can just type

UnitSquare mesh(16, 16);

19
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

Next, we initialize the pair of bilinear and linear forms that we have previ-
ously compiled with FFC:

Poisson::BilinearForm a;
Poisson::LinearForm L(f);

We may now define a PDE from the pair of forms, the mesh and the boundary
conditions:

PDE pde(a, L, mesh, bc);

To solve the PDE, we now just need to call the solve function as follows:

Function U = pde.solve();

Finally, we export the solution u to a file for visualization. Here, we choose

to save the solution in VTK format for visualization in ParaView or MayaVi,
which we do by specifying a file name with extension .pvd:

File file(‘‘poisson.pvd’’);
file << U;

The complete program for Poisson’s equation now looks as follows:

#include <dolfin.h>
#include "Poisson.h"

using namespace dolfin;

int main()
{
// Right-hand side

20
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

class : public Function

{
real eval(const Point& p, unsigned int i)
{
return p.x*sin(p.y);
}
} f;

// Boundary condition
class : public BoundaryCondition
{
void eval(BoundaryValue& value, const Point& p, unsigned int i)
{
if ( std::abs(p.x - 1.0) < DOLFIN_EPS )
value = 0.0;
}
} bc;

// Set up problem
UnitSquare mesh(16, 16);
Poisson::BilinearForm a;
Poisson::LinearForm L(f);
PDE pde(a, L, mesh, bc);

// Compute solution
Function U = pde.solve();

// Save solution to file

File file("poisson.pvd");
file << U;

return 0;
}

2.2.3 Compiling the program

The easiest way to compile the program is to create a Makefile that tells
the standard Unix command make how to build the program. The following

21
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

example shows how to write a Makefile for the above example:

CFLAGS = ‘dolfin-config --cflags‘

LIBS = ‘dolfin-config --libs‘
CXX = ‘dolfin-config --compiler‘
LINK = ‘dolfin-config --linker‘

DEST = dolfin-poisson
OBJECTS = main.o

all: $(DEST)

install:

clean:
-rm -f *.o core *.core $(OBJECTS) $(DEST)

$(DEST): $(OBJECTS)
$(LINK) -o $@ $(OBJECTS) $(CFLAGS) $(LIBS)

.cpp.o:
$(CXX) $(CFLAGS) -c $<

With the Makefile in place, we just need to type make to compile the pro-
gram, generating the executable as the file dolfin-poisson.

2.2.4 Running the program

To run the program, simply type the name of the executable:

# ./dolfin-poisson
Computing mesh connectivity:
Found 289 vertices
Found 512 cells
[...]
Krylov solver (gmres, ilu) converged in 21 iterations.
Saved function [...] to file poisson.pvd in VTK format.

22
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

2.2.5 Visualizing the solution

DOLFIN relies on external programs for visualization. In this example we

chose to save the solution in VTK format, which can be imported into for
example ParaView or MayaVi.

Figure 2.1: The solution of Poisson’s equation (2.1) visualized in ParaView.

23
Chapter 3

Linear algebra

I Developer’s note: This chapter is currently being written. . .

DOLFIN does not have its own linear algebra routines, but instead uses the
external package PETSc [11] for linear algebra functionality.

PETSc is a suite of data structures and routines for the scalable (parallel)
solution of scientific applications modeled by partial differential equations.
It employs the MPI standard for all message-passing communication.

For convenience DOLFIN provides wrappers for some of the most common
linear algebra functionality. For more advanced usage, DOLFIN provides
direct access to the PETSc pointers to be used with the standard PETSc
interface.

3.1 Matrices and vectors

The matrix class Matrix provides wrappers for initializing a sequential sparse
matrix, or a sequential sparse matrix in block compressed row format. For
parallel matrices the PETSc interface has to be used directly.

The code for initializing a sequential sparse M × N matrix takes the form:

25
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

uint M = 100;
uint N = 100;
Matrix A(M,N);

Similarly, the vector class Vector allows for a simple initialization of a M

vector:

Vector b(M);

Further, wrappers for some basic linear algebra functionality, such as matrix
vector multiplication, norms etc., are provided with an intentionally simple
interface, for example, matrix vector multiplication is defined by:

Vector Ax;
A.mult(b,Ax);

For more advanced operations, a pointer to the PETSc matrix and vector is
accessed by mat() and vec() respectively.

3.2 Matrix-free matrices

The DOLFIN class VirtualMatrix represents a matrix-free matrix of di-

mension M × M . The matrix-free matrix is a simple wrapper for a PETSc
shell matrix. The interface is intentionally simple, and for advanced usage
the PETSc Mat pointer is accessed by the function mat().

The class VirtualMatrix enables the use of Krylov subspace methods for
linear systems Ax = b, without having to explicitly store the matrix A. All
that is needed is that the user-defined VirtualMatrix implements multi-
plication with vectors. Note that the multiplication operator needs to be
defined in terms of PETSc data structures (Vec), since it will be called from
PETSc.

26
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

3.3 Linear solvers

A general interface to all linear solvers for systems of the form Ax = b is

provided through the class LinearSolver.

In particular, wrappers for a direct LU solver and an iterative Krylov GMRES

solver are implemented in the classes LU and GMRES.

To solve the linear system Ax = b using GMRES in DOLFIN, simply write:

Vec x;
GMRES solver;
solver.solve(A,x,b);

DOLFIN also provides a wrapper for an eigenvalue solver in PETSc. The

following code computes the eigenvalues of the matrix A,

Vector er, ec;

EigenvalueSolver esolver;
esolver.eigen(A,er,ec);

The real components of the eigenvalues are returned in the vector er and
the complex components of the eigenvalues are returned in the vector ec.
The procedure for computing the eigenvalues of a matrix is computationally
intensive and should only be used for relatively small matrices.

3.4 Preconditioning

The Preconditioner class specifies the interface for user-defined Krylov

method preconditioners. To implement our own preconditioner we only need
to supply a function that approximately solves the linear system given a
right-hand side.

27
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

To change the default preconditioner in the DOLFIN GMRES solver, edit the
constructor of the GMRES class. For example, to choose the ILU preconditioner
for GMRES we write

PC pc;
KSPGetPC(ksp, &pc);
PCSetType(pc, PCILU);

As a complement to the preconditioners available in PETSc, DOLFIN also

uses Hypre [3], which is a library for solving large, sparse linear systems of
equations on massively parallel computers.

To use a preconditioner from Hypre together with a PETSc solver in DOLFIN,

we write:

PCSetType(pc, PCHYPRE );
PCHYPRESetType(pc,"boomeramg");

In particular, the above preconditioner boomeramg is an algebraic multigrid

preconditioner, which is very useful.

28
Chapter 4

The mesh

I Developer’s note: This chapter is currently being written. . .

The concept of a mesh is central in the implementation of adaptive Galerkin

finite element methods for partial differential equations. Related important
concepts include vertices, cells, edges, faces, boundaries, and mesh hierar-
chies. These concepts are all implemented as C++ classes in DOLFIN, as
shown in Figure 4.1.

4.1 Mesh iterators

Algorithms operating on a mesh, including adaptive mesh refinement, can

often be expressed in terms of iterators, i.e., objects used for the traversal of
aggregate structures, such as the list of vertices contained in a mesh. Iter-
ators implemented in DOLFIN include a VertexIterator, CellIterator,
EdgeIterator, FaceIterator, and a MeshIterator. The following code il-
lustrates how to iterate over all vertex neighbors of all vertices of all cells
within a given mesh:

29
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

Figure 4.1: Class diagram of the basic mesh classes in DOLFIN.

30
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

Figure 4.2: Adaptive mesh refinement of triangular and tetrahedral meshes

in DOLFIN.

for (CellIterator c(m); !c.end(); ++c)

for (VertexIterator v1(c); !v1.end(); ++v1)
for (VertexIterator v2(n1); !v2.end(); ++v2)
cout << *v2 << endl;

4.2 Mesh refinement

Adaptive mesh refinement is implemented in DOLFIN for triangular meshes

(in 2D) and tetrahedral meshes (in 3D), see Figure 4.2, based on the algo-
rithm given in [14]. To refine a mesh, the cells (triangles or tetrahedrons) are
first marked according to some criterion for refinement, before the mesh is
refined. A hierarchy of meshes, that can be used for example in a multigrid
computation, is automatically created.

The following example illustrates how to iterate over the Cells of a Mesh to
mark some Cells for refinement, before refining the Mesh:

31
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

// Mark cells for refinement

for (CellIterator cell(mesh); !cell.end(); ++cell)
if ( ... )
cell->mark();

// Refine mesh
mesh.refine();

It is also possible to directly mark all Cells for refinement to refine the Mesh
uniformly:

// Refine all cells

mesh.refineUniformly();

32
Chapter 5

Functions

I Developer’s note: Since this chapter was written, the Function class has
seen a number of improvements which are not covered here. Chapter needs
to be updated.

The central concept of a function on a domain Ω ⊂ Rd is modeled by the class

Function, which is used in DOLFIN to represent coefficients or solutions of
partial differential equations.

5.1 Basic properties

The following basic properties hold for all Functions:

• A Function can be scalar or vector-valued;

• A Function can be evaluated at each Vertex of a Mesh;

• A Function can be restricted to each local Cell of a Mesh;

• The underlying representation of a Function may vary.

33
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

Depending on the actual underlying representation of a Function, it may

also be possible to evaluate a Function at any given Point.

5.1.1 Representation

Currently supported representations of Functions include discrete Functions

and user-defined Functions. These are discussed in detail below.

5.1.2 Evaluation

All Functions can be evaluated at the Vertices of a Mesh. The following

example illustrates how to evaluate a scalar Function at each Vertex of a
given Mesh:

Function f;
Mesh mesh;

for (VertexIterator vertex(mesh); !vertex.end(); ++vertex)

cout << ‘‘Value at vertex ‘‘ << *vertex << ‘‘: ‘‘
<< f(*vertex) << endl;

If the Function is vector-valued, an additional argument is needed to spec-

ify the component. The following example illustrates how to evaluate all
components of a vector-valued Function at all each Vertex of a given Mesh:

Function f;
Mesh mesh;

for (VertexIterator vertex(mesh); !vertex.end(); ++vertex)

for (unsigned int i = 0; i < u.vectordim(); i++)
cout << ‘‘Value of component ‘‘ << i << ‘‘ at vertex ‘‘
<< *vertex << ‘‘: ‘‘ << f(*vertex, i) << endl;

34
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

If allowed by the underlying representation, a Function u may also be eval-

uated directly at any given Point:

Point p(0.5, 0.5, 0.5);

cout << ‘‘Value at p = ‘‘ << p << ‘‘: ‘‘ << f(p) << endl;

As in the case of evaluation at a Vertex, the component index may be given

as an additional argument for a vector-valued Function.

5.1.3 Assignment

One Function may be assigned to another Function:

Function f;
Function g = f;

5.1.4 Components and sub functions

If a Function is vector-valued, a new Function may be created to represent

any given component of the original Function, as illustrated by the following
example:

Function f; // Function with three components

Function f0 = f[0]; // first component
Function f1 = f[1]; // second component
Function f2 = f[2]; // third component

If a Function represents a mixed function (one defined in terms of a mixed

FiniteElement, see below), then indexing has the effect of picking out sub
functions. With w a Function representing the discrete solution w = (U, P )

35
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

of a Stokes or Navier-Stokes system (with U the vector-valued velocity and

P the scalar pressure), the following example illustrates how to pick sub
functions and components of w:

Function w; // mixed Function (U, P)

U = w[0]; // first sub function (velocity)
P = w[1]; // second sub function (pressure)
U0 = U[0]; // first component of the velocity
U1 = U[1]; // second component of the velocity
U2 = U[2]; // third component of the velocity

Note that picking a component or sub function creates a new Function that
shares data with the original Function.

5.1.5 Output

A Function can be written to a file in various file formats. To write a

Function u to file in VTK format, suitable for viewing in ParaView or
MayaVi, create a file with extension .pvd:

File file(‘‘solution.pvd’’);
file << U;

For further details on available file formats, see Chapter 9.

5.2 Discrete functions

A discrete Function is defined in terms of a Vector of nodal values (degrees

of freedom), a Mesh and a FiniteElement specifying the distribution of the
nodal values on the Mesh. In particular, a discrete Function is given by a

36
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

linear combinations of basis functions:

X
N
v= v i φi , (5.1)
i=1

where {φi }Ni=1 is the global basis of the finite element space defined by the
Mesh and the FiniteElement, and the nodal values {vi }N i=1 are given by the
values of a Vector.

Note that a discrete Function may not be evaluated at arbitrary points (only
at each Vertex of a Mesh).

5.2.1 Creating a discrete function

A discrete Function can be initialized in several ways. In the simplest case,

only a Vector x of nodal values needs to be specified:

Vector x;

Function f(x);

If possible, DOLFIN will then automatically try to determine the Mesh and
the FiniteElement.

In some cases, it is necessary to also supply a Mesh when initializing a discrete

Function:

Vector x;
Mesh mesh;

Function f(x, mesh);

If possible, DOLFIN will then automatically try to determine the FiniteElement.

37
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

In general however, a discrete Function must be initialized from a given

Vector, a Mesh and a FiniteElement:

Vector x;
Mesh mesh;
FiniteElement element;

Function f(x, mesh, element);

5.2.2 Accessing discrete function data

It is possible to access the data of a discrete Function, including the associ-

ated Vector, Mesh and FiniteElement:

Vector& x = u.vector();
Mesh& mesh = u.mesh();
FiniteElement& element = u.element();

5.2.3 Attaching discrete function data

After a discrete Function has been initialized, it is possible to associate or

reassociate data with the Function:

Vector x;
Mesh mesh;
FiniteElement element;

Function f(x);
f.attach(mesh);
f.attach(element);

38
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

Usually, the FiniteElement is given by the BilinearForm defining the prob-

lem. Considering the Poisson example in Chapter 2, a Function u represent-
ing the solution can be initialized as follows:

Vector x;
Mesh mesh;
Function f(x, mesh);

Poisson::BilinearForm a;

FiniteElement& element = a.trial();

f.attach(element);

In this example, the Function f represents a function in the trial space for
the BilinearForm a.

5.3 User-defined functions

In the simplest case, a user-defined Function is just an expression in terms

of the coordinates and is typically used for defining source terms and initial
conditions. For example, a source term could be given by
f = f (x, y, z) = xy sin(z/π). (5.2)

There are two ways to create a user-defined Function; either by creating

a sub class of Function or by creating a Function from a given function
pointer.

5.3.1 Creating a sub class

A user-defined Function may be defined by creating a sub class of Function

and overloading the eval() function. The following example illustrates how
to create a Function representing the function in (5.2):

39
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

class Source : public Function

{
real eval(const Point& p, unsigned int i)
{
return x*y*sin(z / DOLFIN_PI);
}
};

Source f;

To create a vector-valued Function, the vector dimension must be supplied

to the constructor of Function:

class Source : public Function

{
public:

Source() : Function(3) {}

real eval(const Point& p, unsigned int i)

{
if ( i == 0 )
return 0.0;
else if ( i == 1 )
return x*y*sin(z / DOLFIN_PI);
else
return x + y;
}
};

Source f;

40
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

5.3.2 Specifying a function-pointer

A user-defined Function may alternatively be defined by specifying a func-

tion pointer. The following example illustrates an alternative way of creating
a Function representing the function in (5.2):

real source(const Point& p, unsigned int i)

{
return x*y*sin(z / DOLFIN_PI);
}

Function f(source);

As before, for vector-valued Functions, the vector dimension must be sup-

plied to the constructor of Function:

real source(const Point& p, unsigned int i)

{
if ( i == 0 )
return 0.0;
else if ( i == 1 )
return x*y*sin(z / DOLFIN_PI);
else
return x + y;
}

Function f(source, 3);

5.3.3 Cell-dependent functions

In some cases, it may be convenient to define a Function in terms of proper-

ties of the current Cell. One such example is a Function that at any given
point takes the value of the mesh size at that point.

41
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

The following example illustrates how to create such as Function by over-

loading the eval() function:

class MeshSize : public Function

{
real eval(const Point& p, unsigned int i)
{
return cell().diameter();
}
}

MeshSize h;

Note that the current Cell is only available during assembly and has no
meaning otherwise. It is thus not possible to write the Function h to file,
since the current Cell is not available when evaluating a Function at any
given Vertex. Furthermore, note that the current Cell is not available when
creating a Function from a function pointer.

5.4 Time-dependent functions

I Developer’s note: Write about time-dependent and pseudo time-dependent

functions.

42
Chapter 6

Ordinary differential equations

I Developer’s note: This chapter is currently being written. . .

43
Chapter 7

Partial differential equations

I Developer’s note: This chapter is currently being written. . .

I Developer’s note: Use U for discrete solution and U for corresponding

representation in the code

DOLFIN provides a general interface for defining a partial differential equa-

tion (PDE) in variational form. The variational form is compiled with FFC,
which generates code for the assembly of a matrix and a vector, correspond-
ing to the discretization of the PDE with a user-defined finite element method
(FEM), where the basis functions of the FEM space are constructed using
FIAT.

7.1 Boundary value problems

As a prototype of a boundary value problem in Rd we consider the scalar

Poisson equation with homogeneous Dirichlet boundary conditions

− ∆u(x) = f (x) x ∈ Ω ⊂ Rd (7.1)

u(x) = 0 x ∈ ∂Ω.

45
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

7.2 Variational formulation

A variational formulation of (7.1) takes the form: find u ∈ V such that

a(v, u) = L(v) ∀v ∈ V̂ , (7.2)
where a(·, ·) : V̂ × V → R is a bilinear form acting on V̂ × V , with V̂ and V
the test space and trial space respectively, defined by
Z Z
∂v ∂u
a(v, u) = ∇v · ∇u dx = dx, (7.3)
Ω Ω ∂xi ∂xi

where we employ tensor notation so that the double index i means summation
from i = 1, ..., d, and L(·) : V̂ → R is a linear form acting on the test space
V̂ , defined by Z
L(v) = vf dx. (7.4)
Ω

For this problem we typically use V = V̂ = H01 (Ω), with H01 (Ω) the standard
Sobolev space of square integrable functions with also their first derivatives
square integrable (in the Lebesgue sense), with the functions being zero on
the boundary (in the sense of traces).

The FEM method for (7.2) is now: find U ∈ Vh such that

a(v, U ) = L(v) ∀v ∈ V̂h , (7.5)
where Vh ⊂ V and V̂h ⊂ V̂ are finite dimensional subspaces of dimension
M . The finite element spaces Vh , V̂h are characterized by their sets of basis
functions {ϕi }M M
i=1 , {ϕ̂i }i=1 . The FEM method (7.5) is thus specified by the
variational form and the basis functions of Vh and V̂h .

7.3 Finite elements and FIAT

Finite element basis functions in DOLFIN are defined using FIAT, which
supports the generation of arbitrary order Lagrange finite elements on lines,
triangles, and tetrahedra. Upcoming versions of FIAT will also support Her-
mite and nonconforming elements as well as H(div) and H(curl) elements
such as Raviart-Thomas and Nedelec.

46
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

7.4 Compiling the variational form with FFC

In DOLFIN a PDE is defined in variational form using tensor notation in a

.form file, which is compiled using FFC.

In the language of FFC, with Vh = V̂h the space of piecewise linear Lagrange
finite elements on a tetrahedral mesh, (7.5) is defined as:

element = FiniteElement("Lagrange", "tetrahedron", 1)

v = BasisFunction(element)
u = BasisFunction(element)
f = Function(element)

a = v.dx(i)*u.dx(i)*dx
L = v*f*dx

where *dx signifies integration over the domain Ω, and the finite element
space is constructed using FIAT. DOLFIN is not communicating directly
with FIAT, but only through FFC in the definition of the variational form in
the .form file.

Compiling the .form file with

# ffc Poisson.form

generates a file Poisson.h, containing classes for the bilinear form a(·, ·) and
the linear form L(·), and classes for the finite element spaces Vh and V̂h .

7.5 Element matrices and vectors

The element matrices and vectors for a given cell may be factored into two
tensors, with one tensor depending on the geometry of the cell, and the

47
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

other tensor only involving integration of products of basis functions and

their derivatives over the reference element.

For efficiency in the computation of the element matrices and vectors, FFC
precomputes the tensors that are independent of the geometry of a certain
cell.

7.6 Assemble matrices and vectors

The class FEM automates the assembly algorithm, constructing a linear system
of equations from a PDE, given in the form of a variational problem (7.2),
with a bilinear form a(·, ·) and a linear form L(·).

The classes BilinearForm and LinearForm are automatically generated by

FFC, and to assemble the corresponding matrix and vector for the Poisson
problem (7.2) with source term f , we write:

Poisson::BilinearForm a;
Poisson::LinearForm L(f);

Mesh mesh;
Mat A;
Vec b;

FEM::assemble(a,L,A,b,mesh);

In the assemble() function the element matrices and vectors are computed
by calling the function eval() in the classes Bilinearform and Linearform.
The eval() functions at a certain element in the assembly algorithm take as
argument an AffineMap object, describing the mapping from the reference
element to the actual element, by computing the Jacobian J of the mapping
(also J −1 and det(J) are computed).

48
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

7.7 Specifying boundary conditions and data

The boundary conditions are specified by defining a new subclass of the class
BoundaryCondition, which we here will name MyBC:

class MyBC : public BoundaryCondition

{
const BoundaryValue operator() (const Point& p)
{
BoundaryValue value;
if ( std::abs(p.x - 0.0) < DOLFIN_EPS ) value = 0.0;
if ( std::abs(p.x - 1.0) < DOLFIN_EPS ) value = 0.0;
if ( std::abs(p.y - 0.0) < DOLFIN_EPS ) value = 0.0;
if ( std::abs(p.y - 1.0) < DOLFIN_EPS ) value = 0.0;
if ( std::abs(p.z - 0.0) < DOLFIN_EPS ) value = 0.0;
if ( std::abs(p.z - 1.0) < DOLFIN_EPS ) value = 0.0;
return value;
}
};

where we have assumed homogeneous Dirichlet boundary conditions for the

unit cube. We only need to specify the boundary conditions explicitly on
the Dirichlet boundary. On the remaining part of the boundary, homoge-
neous Neumann boundary conditions are automatically imposed weakly by
the variational form.

The boundary conditions are then imposed as an argument to the assemble()

function:

MyBC bc;
FEM::assemble(a,L,A,b,mesh,bc);

There is currently no easy way to impose non-homogeneous Neumann bound-

ary conditions or other combinations of boundary conditions. This will be
added to a future release of DOLFIN.

49
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

The right-hand side f of (7.1) is similarly specified by defining a new subclass

of Function, which we here will name MyFunction, and overloading the
evaluation operator:

class MyFunction : public Function

{
real operator() (const Point& p) const
{
return p.x*p.z*sin(p.y);
}
};

with the source f (x, y, z) = xz sin(y).

7.8 Initial value problems

A time dependent problem has to be discretized in time manually, and the

resulting variational form is then discretized in space using FFC similarly to
a stationary problem, with the solution at previous time steps provided as
data to the form file.

For example, the form file Heat.form for the heat equation discretized in
time with the implicit Euler method, takes the form:

v = BasisFunction(scalar) # test function

U1 = BasisFunction(scalar) # value at next time step
U0 = Function(scalar) # value at previous time step
f = Function(scalar) # source term
k = Constant() # time step

a = v*U1*dx + k*v.dx(i)*U1.dx(i)*dx
L = v*U0*dx + v*f*dx

50
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

which generates a file Heat.h when compiled with FFC. To initializations

the corresponding forms we write:

real k; // time step

Vector x0; // vector containing dofs for u0
Function U0(x0, mesh); // solution at previous time step

Heat::BilinearForm a(k);
Heat::LinearForm L(U0, f, k);

51
Chapter 8

Nonlinear solver

I Developer’s note: This chapter is currently being written. . .

DOLFIN provides tools for solving nonlinear equations of the form

F (x) = 0 (8.1)

where F : Rn → Rn . The nonlinear solvers are based on Newton’s method

and utilise functions from PETSc [11].

To use the nonlinear solver, a nonlinear function must be defined. The non-
linear solver is then initialised with this function and a solution computed.

8.1 Nonlinear functions

To solve a nonlinear problem, the user must defined a class which . The class
should be derived from the DOLFINclass NonlinearFunction. The class
should contain the necessary functions to form the function F (u) and the
Jacobian matrix J = ∂F/∂u. The precise form of the user defined class will
depend on the PDE being solved and the numerical method. The structu of
a user defined class MyNonlinearFunction is shown below.

53
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

class MyNonlinearFunction : public NonlinearFunction

{
public:

// Constructor
MyNonlinearFunction() : NonlinearFunction(){}

// Compute F(u)
void F(Vector& b, const Vector& x)
{
// Insert F(u) into the vector b
}

// Compute J
void J(Matrix& A, const Vector& x)
{
// Insert the Jacobian into the matrix A
}

dolfin::uint size()
{
// Return the dimension of the Jacobian matrix
}

dolfin::uint nzsize()
{
// Return the maximum number of zeroes per row of J
}

private:
// Pointers to objects with which F(u) is defined
};

54
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

8.2 Newton solver

8.2.1 Linear solver

8.2.2 Application of Dirichlet boundary conditions

The application of inhomogenuous Dirichlet boundary conditions in the con-

text of a Newton solver requires particular attention.

8.2.3 Newton solver parameters

8.2.4 Application of Dirichlet boundary conditions

8.3 Incremental Newton solver

55
Chapter 9

Input/output

DOLFIN relies on external programs for pre- and post-processing, which

means that computational meshes must be imported from file (pre-processing)
and computed solutions must be exported to file and then imported into an-
other program for visualization (post-processing). To simplify this process,
DOLFIN provides support for easy interaction with files and includes output
formats for a number of visualization programs.

9.1 Files and objects

A file in DOLFIN is represented by the class File and reading/writing data

is done using the standard C++ operators >> (read) and << (write).

Thus, if file is a File and object is an object of some class that can be
written to file, then the object can be written to file as follows:

file << object;

Similarly, if object is an object of a class that can be read from file, then
data can be read from file (overwriting any previous data held by the object)

57
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

as follows:

file >> object;

The format (type) of a file is determined by its filename suffix, if not otherwise
specified. Thus, the following code creates a File for reading/writing data
in DOLFIN XML format:

File file(‘‘data.xml’’);

A complete list of file formats and corresponding file name suffixes is given
in Table 9.1.

Alternatively, the format of a file may be explicitly defined. One may thus
create a file named data.xml for reading/writing data in GNU Octave for-
mat:

File file(‘‘data.xml’’, File::octave);

Suffix Format Description

.xml/.xml.gz File::xml DOLFIN XML
.pvd File::vtk VTK
.dx File::opendx OpenDX
.m File::octave GNU Octave
(.m) File::matlab MATLAB
.tec File::tecplot Tecplot
.msh/.res File::gid GiD

Table 9.1: File formats and corresponding file name suffixes.

Although many of the classes in DOLFIN support file input/output, it is not

supported by all classes and the support varies with the choice of file format.
A summary of supported classes/formats is given in Table 9.2.

58
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

I Developer’s note: Some of the file formats are partly broken after changing
the linear algebra backend to PETSc. (Do grep FIXME in src/kernel/io/.)

Format Vector Matrix Mesh Function Sample

File::xml in/out in/out in/out — —
File::vtk — — out out —
File::opendx — — out out —
File::octave out out out out out
File::matlab out out out out out
File::tecplot — — out out —
File::gid — — out out —

Table 9.2: Matrix of supported combinations of classes and file formats for
input/output in DOLFIN.

9.2 File formats

In this section, we give some pointers to each of the file formats supported by
DOLFIN. For detailed information, we refer to the respective user manual
of each format/program.

I Developer’s note: This section needs to be improved and expanded. Any

contributions are welcome.

9.2.1 DOLFIN XML

DOLFIN XML is the native format of DOLFIN. As the name says, data
is stored in XML ASCII format. This has the advantage of being a robust
and human-readable format, and if the files are compressed there is little
overhead in terms of file size compared to a binary format.

DOLFIN automatically handles gzipped XML files, as illustrated by the fol-

lowing example which reads a Mesh from a compressed DOLFIN XML file
and saves the mesh to an uncompressed DOLFIN XML file:

59
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

Mesh mesh;

File in(‘‘mesh.xml.gz’’);
in >> mesh;

File out(‘‘mesh.xml’’);
out << mesh;

The same thing can of course be accomplished by

# gunzip -c mesh.xml.gz > mesh.xml

on the command-line.

There is currently no visualization tool that can read DOLFIN XML files,
so the main purpose of this format is to save and transfer data.

9.2.2 VTK

Data saved in VTK format [13] can be visualized using various packages. The
powerful and freely available ParaView [10] is recommended. Alternatively,
VTK data can be visualized in MayaVi [5], which is recommended for quality
vector PostScript output. Time-dependent data is handled automatically in
the VTK format.

The below code illustrates how to export a function in VTK format:

Function u;

File out(‘‘data.pvd’’);
out << u;

60
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

The sample code produces the file data.pvd, which can be read by Par-
aView. The file data.pvd contains a list of files which contain the results
computed by DOLFIN. For the above example, these files would be named
dataXXX.vtu, where XXX is a counter which is incremented each time the
function is saved. If the function u was to be saved three times, the files

data000000.vtu
data000001.vtu
data000002.vtu

would be produced. Individual snapshots can be visualized by opening the

desired file with the extension .vtu using ParaView.

ParaView can produce on-screen animations. High quality animations in

various formats can be produced using a combination of ParaView and MEn-
coder [6].

I Developer’s note: Add MEncoder example to create animation.

9.2.3 OpenDX

OpenDX [9] is a powerful free visualization tool based on IBM’s Visualization

Data Explorer. To visualize data with OpenDX, a user needs to build a
visual program that instructs OpenDX how to extract and visualize relevant
parts of your data. DOLFIN provides a ready-made visual program suitable
for visualization of DOLFIN data in OpenDX. The visual program can be
found in the subdirectory src/utils/opendx/ of the DOLFIN source tree
(file dolfin.net and accompanying configuration dolfin.cfg).

9.2.4 GNU Octave

GNU Octave [7] is a free clone of MATLAB that can be used to visualize
solutions computed in DOLFIN, using the commands pdemesh, pdesurf

61
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

and pdeplot. These commands are normally not part of GNU Octave but
are provided by DOLFIN in the subdirectory src/utils/octave/ of the
DOLFIN source tree. These commands require the external program ivview
included in the open source distribution of Open Inventor [8]. (Debian users
install the package inventor-clients.)

To visualize a solution computed with DOLFIN and exported in GNU Octave

format, first load the solution into GNU Octave by just typing the name of
the file without the .m suffix. If the solution has been saved to the file
poisson.m, then just type

octave:1> poisson

The solution can now be visualized using the command

octave:2> pdesurf(points, cells, u)

or to visualize just the mesh, type

octave:3> pdesurf(points, edges, cells)

9.2.5 MATLAB

Since MATLAB [4] is not free, users are encouraged to use GNU Octave
whenever possible. That said, data is visualized in much the same way
in MATLAB as in GNU Octave, using the MATLAB commands pdemesh,
pdesurf and pdeplot.

9.2.6 Tecplot

Tecplot [12] is a proprietary visualization tool. The Tecplot format is not

actively maintained and may be removed in future versions of DOLFIN (if

62
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

there is not sufficient interest to maintain the format).

9.2.7 GiD

GiD [2] is a proprietary visualization tool. The GiD format is not actively
maintained and may be removed in future versions of DOLFIN (if there is
not sufficient interest to maintain the format).

9.3 Converting between file formats

DOLFIN supplies a script for easy conversion between different file formats.
The script is named dolfin-convert and can be found in the directory
src/utils/convert/ of the DOLFIN source tree. The only supported file
formats are currently the Medit .mesh format (which can be generated by
TetGen), the .gmsh format (generated by Gmsh) and the DOLFIN XML
mesh format:

# dolfin-convert mesh.mesh mesh.xml

9.4 A note on new file formats

With some effort, DOLFIN can be expanded with new file formats. Any con-
tributions are welcome. If you wish to contribute to DOLFIN, then adding
a new file format (or improving upon an existing file format) is a good place
to start. Take a look at one of the current formats in the subdirectory
src/kernel/io/ of the DOLFIN source tree to get a feeling for how to de-
sign the file format, or ask at [email protected] for directions.

Also consider contributing to the dolfin-convert script by adding a con-

version routine for your favorite format. The script is written in Python and
should be easy to extend with new formats.

63
Chapter 10

The log system

DOLFIN provides provides a simple interface for uniform handling of log

messages, including warnings and errors. All messages are collected to a
single stream, which allows the destination and formatting of the output
from an entire program, including the DOLFIN library, to be controlled by
the user.

10.1 Generating log messages

Log messages can be generated using the function dolfin info() available
in the dolfin namespace:

void dolfin_info(const char *message, ...);

which works similarly to the standard C library function printf. The fol-
lowing examples illustrate the usage of dolfin info():

dolfin_info(‘‘Solving linear system.’’);

dolfin_info(‘‘Size of vector: %d.’’, x.size());
dolfin_info(‘‘R = %.3e (TOL = %.3e)’’, R, TOL);

65
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

As an alternative to dolfin info(), DOLFIN provides a C++ style in-

terface to generating log messages. Thus, the above examples can also be
implemented as follows:

cout << ‘‘Solving linear system.’’ << endl;

cout << ‘‘Size of vector: ‘‘ << x.size() << ‘‘.’’ << endl;
cout << ‘‘R = ‘‘ << R << ‘‘ (TOL = ‘‘ << TOL << ‘‘)’’ << endl;

Note the use of dolfin::cout and dolfin::endl from the dolfin names-
pace, corresponding to the standard standard std::cout and std::endl in
namespace std. If log messages are directed to standard output (see below),
then dolfin::cout and std::cout may be mixed freely.

Most classes provided by DOLFIN can be used together with dolfin::cout

and dolfin::endl to display short informative messages about objects:

Matrix A(10, 10);

cout << A << endl;

To display detailed information for an object, use the member function

disp():

Matrix A(10, 10);

A.disp();

Use with caution for large objects. For a Matrix, calling disp() will displays
all matrix entries.

10.2 Warnings and errors

Warnings and error messages can be generated using the macros

66
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

dolfin_warning(message);
dolfin_error(message);

In addition to displaying the given string message, the macro dolfin error()
also displays information about the location of the code that generated the
error (file, function name and line number). Once an error is encountered,
the program is stopped.
Note that in order to pass formatting strings and additional arguments to
warnings or errors, the variations dolfin error1(), dolfin error2() and
so on must be used, as illustrated by the following examples:

dolfin_error(‘‘GMRES solver did not converge.’’);

dolfin_error1(‘‘Unable to find face opposite to node %d.’’, n);
dolfin_error2(‘‘Unable to find edge between nodes %d and %d.’’, n0, n1);

10.3 Debug messages and assertions

The macro dolfin debug() works similarly to dolfin info():

dolfin_debug(message);

but in addition to displaying the given message, information is printed about

the location of the code that generated the debug message (file, function
name and line number).

Note that in order to pass formatting strings and additional arguments with
debug messages, the variations dolfin debug1(), dolfin debug2() and so
on, depending on the number of arguments, must be used.

Assertions can often be a helpful programming tool. Use assertions whenever

you assume something about about a variable in your code, such as assum-
ing that given input to a function is valid. DOLFIN provides the macro
dolfin assert() for creating assertions:

67
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

dolfin assert(check);

This macro accepts a boolean expression and if the expression evaluates to

false, an error message is displayed, including the file, function name and
line number of the assertion, and a segmentation fault is raised (to enable
easy attachment to a debugger). The following examples illustrate the use
of dolfin assert():

dolfin_assert(i >= 0);

dolfin_assert(i < n);
dolfin_assert(cell.type() == Cell::triangle);
dolfin_assert(cell.type() == Cell::tetrahedron);

Note that assertions are only active when compiling DOLFIN and your
program with DEBUG defined (configure option --enable-debug or compiler
flag -DDEBUG). Otherwise, the macro dolfin assert() expands to nothing,
meaning that liberal use of assertions does not affect performance, since as-
sertions are only present during development and debugging.

10.4 Task notification

The two functions dolfin begin() and dolfin end() available in the dolfin
name space can be used to notify the DOLFIN log system about the begin-
ning and end of a task:

void dolfin_begin();
void dolfin_end();

Alternatively, a string message (or a formatting string with optional argu-

ments) can be supplied:

68
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

void dolfin_begin(const char* message, ...);

void dolfin_end(const char* message, ...);

These functions enable the DOLFIN log system to display messages, warn-
ings and errors hierarchically, by automatically indenting the output pro-
duced between calls to dolfin begin() and dolfin end(). A program may
contain an arbitrary number of nested tasks.

10.5 Progress bars

The DOLFIN log system provides the class Progress for simple creation of
progress sessions. A progress session automatically displays the progress of
a computation using a progress bar.

If the number of steps of a computation is known, a progress session should

be defined in terms of the number of steps and updated in each step of the
computation as illustrated by the following example:

Progress p(‘‘Assembling’’, mesh.noCells());

for (CellIterator c(mesh); !c.end(); ++c)
{
...
p++;
}

It is also possible to specify the step number explicitly by assigning an integer

to the progress session:

Progress p(‘‘Iterating over vector’’, x.size())

for (uint i = 0; i < x.size(); i++)
{
...

69
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

p = i;
}

Alternatively, if the number of steps is unknown, the progress session needs

to be updated with the current percentage of the progress:

Progress p(‘‘Time-stepping’’);
while ( t < T )
{
...
p = t / T;
}

The progress bar created by the progress session will only be updated if the
progress has changed significantly since the last update (by default at least
10%). The amount of change needed for an update can be controlled using
the parameter ‘‘progress step’’:

dolfin_set(‘‘progress step’’, 0.01);

Note that several progress sessions may be created simultaneously, or nested

within tasks.

10.6 Controlling the destination of output

By default, the DOLFIN log system directs messages to standard output (the
terminal). Other options include directing messages to a curses interface or
turning of messages completely. To specify the output destination, use the
function dolfin output() available in the dolfin namespace:

void dolfin_output(const char* destination);

70
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

where destination is one of ‘‘plain text’’ (standard output), ‘‘curses’’

(curses interface) or ‘silent’’ (no messages printed).

When messages are directed to the DOLFIN curses interface, a text-mode

graphical and interactive user-interface is started in the current terminal
window. To see a list of options, press ’h’ for help. The curses-interface is
updated periodically but the function dolfin update() can be used to force
a refresh of the display.

It is possible to switch the DOLFIN log system on or off using the function
dolfin log() available in the dolfin namespace. This function accepts as
argument a bool, specifying whether or not messages should be directed
to the current output destination. This function can be useful to suppress
excessive logging, for example when calling a function that generates log
messages multiple times:

GMRES gmres;
while ( ... )
{
...
dolfin_log(false);
gmres.solve(A, x, b);
dolfin_log(true);
...
}

71
Chapter 11

The parameter system

I Developer’s note: Since this chapter was written, the DOLFIN parame-
ter system has been completely redesigned and now supports localization of
parameters to objects or hierarchies of objects. Chapter needs to be updated.

DOLFIN keeps a global database of parameters that control the behavior of

the various components of DOLFIN. Parameters are controlled using a uni-
form type-independent interface that allows retrieving the values of existing
parameters, modifying existing parameters and adding new parameters to
the database.

11.1 Retrieving the value of a parameter

To retrieve the value of a parameter, use the function get() available in the
dolfin namespace:

Parameter get(std::string key);

This function accepts as argument a string key and returns the value of the
parameter matching the given key. An error message is printed through the

73
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

log system if there is no parameter with the given key in the database.

The value of the parameter is automatically cast to the correct type when
assigning the value of get() to a variable, as illustrated by the following
examples:

real TOL = get(‘‘tolerance’’);

int num_samples = get(‘‘number of samples’’);
bool solve_dual = get(‘‘solve dual problem’’);
std::string filename = get(‘‘file name’’);

Note that there is a small cost associated with accessing the value of a pa-
rameter, so if the value of a parameter is to be used multiple times, then it
should be retrieved once and stored in a local variable as illustrated by the
following example:

int num_samples = get(‘‘number of samples’’);

for (int i = 0; i < num_samples; i++)
{
...
}

11.2 Modifying the value of a parameter

To modify the value of a parameter, use the function set() available in the
dolfin namespace:

void set(std::string key, Parameter value);

This function accepts as arguments a string key together with the corre-
sponding value. The value type should match the type of parameter that is

74
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

being modified. An error message is printed through the log system if there
is no parameter with the given key in the database.

The following examples illustrate the use of set():

set(‘‘tolerance’’, 0.01);
set(‘‘number of samples’’, 10);
set(‘‘solve dual problem’’, true);
set(‘‘file name’’, ‘‘solution.xml’’);

Note that changing the values of parameters using set() does not change
the values of already retrieved parameters; it only changes the values of
parameters in the database. Thus, the value of a parameter must be changed
before using a component that is controlled by the parameter in question.

11.3 Adding a new parameter

To add a parameter to the database, use the function add() available in the
dolfin namespace:

void add(std::string key, Parameter value);

This function accepts two arguments: a unique key identifying the new pa-
rameter and the value of the new parameter.

The following examples illustrate the use of add():

add(‘‘tolerance’’, 0.01);
add(‘‘number of samples’’, 10);
add(‘‘solve dual problem’’, true);
add(‘‘file name’’, ‘‘solution.xml’’);

75
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

11.4 Saving parameters to file

The following code illustrates how to save the current database of parameters
to a file in DOLFIN XML format:

File file(‘‘parameters.xml’’);
file << ParameterSystem::parameters;

When running a simulation in DOLFIN, saving the parameter database to a

file is an easy way to document the set of parameters used in the simulation.

11.5 Loading parameters from file

The following code illustrates how to load a set of parameters into the current
database of parameters from a file in DOLFIN XML format:

File file(‘‘parameters.xml’’);
file >> ParameterSystem::parameters;

The following example illustrates how to specify a list of parameters in the

DOLFIN XML format

<?xml version=’’1.0’’ encoding=’’UTF-8’’?>

<dolfin xmlns:dolfin=’’http://www.fenics.org/dolfin/’’>
<parameters>
<parameter name=’’tolerance’’ type=’’real’’ value=’’0.01’’/>
<parameter name=’’number of samples’’ type=’’int’’ value=’’10’’/>
<parameter name=’’solve dual problem’’ type=’’bool’’ value=’’false’’/>
<parameter name=’’file name’’ type=’’string’’ value=’’solution.xml’’/>
</parameters>
</dolfin>

76
Chapter 12

Solvers

I Developer’s note: This chapter is currently being written. . .

DOLFIN provides a number of pre-defined PDE solvers (called “modules”

in the source structure) by default. The solver interface is intentionally very
simple to facilitate users writing their own solvers. These are the pre-defined
solvers:

1. Poisson
2. Convection-Diffusion
3. Navier-Stokes
4. Elasticity

A solver for a PDE should provide the following interface:

1. a constructor which takes a mesh, equation coefficients and possibly

additional data.
2. a solve() method which solves the equation given the specified data.
3. a static solve() function which constructs and solves the equation.

77
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

FIXME:List solvers, then present in detail, include lots of nice images with
solver output

12.1 Poisson’s equation

Poisson’s equation with Dirichlet and homogeneous Neumann boundary con-

ditions:

−∆u = f in Ω,
u = gD on Γ1 , (12.1)
−∂n u = 0 on Γ2

The variational formulation is given by

R R
Ω
∇u · ∇v dx = Ω
f v dx ∀v. (12.2)

The boundary conditions are enforced strongly and thus don’t appear in the
variational formulation.

12.1.1 Usage

The API for the Poisson solver:

// Create Poisson solver

PoissonSolver(Mesh& mesh, Function& f, BoundaryCondition& bc);

// Solve Poisson’s equation

void solve();

// Solve Poisson’s equation (static version)

static void solve(Mesh& mesh, Function& f, BoundaryCondition& bc);

78
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

A simple example of using the solver:

int main()
{
Mesh mesh("mesh.xml.gz");
MyFunction f;
MyBC bc;

PoissonSolver::solve(mesh, f, bc);

return 0;
}

Where “f” is a Function specifying the right-hand side of the equation and
“bc” is a BoundaryCondition.

12.1.2 Performance

The solver is an illustrative example and performance has not been a goal.
It uses a GMRES linear solver, where a multi-grid linear solver would give
optimal performance.

12.1.3 Limitations

The solver is meant to be the simplest example solver, and therefore some
simplifications have been made. Typically the general form of Poisson’s equa-
tion includes a diffusion coefficient which has been omitted here.

79
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

12.2 Convection–diffusion

The convection-diffusion equation with Dirichlet and homogeneous Neumann

boundary conditions is given by:

u̇ + b · ∇u − ∇ · (a∇u) = f in Ω × (0, T ],
u = gD on Γ1 × (0, T ],
(12.3)
−∂n u = 0 on Γ2 × (0, T ],
u(·, 0) = u0 in Ω,

where the convection is given by the vector b = b(x, t) and the diffusion is
given by a = a(x, t).

The variational formulation is:

FIXME:Stabilized convection-diffusion

This is a stabilized FEM-formulation, so the solver can handle convection-

dominated problems.

The time integration is done using cG(1) (Crank-Nicolson).

12.2.1 Usage

The API for the convection-diffusion solver:

// Create convection-diffusion solver

ConvectionDiffusionSolver(Mesh& mesh, Function& w, Function& f,
BoundaryCondition& bc);

// Solve convection-diffusion
void solve();

80
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

// Solve convection-diffusion (static version)

static void solve(Mesh& mesh, Function& w, Function& f,
BoundaryCondition& bc);

A simple example of using the solver:

int main()
{
dolfin_output("curses");

Mesh mesh("dolfin.xml.gz");
Convection w;
Source f;
MyBC bc;

ConvectionDiffusionSolver::solve(mesh, w, f, bc);

return 0;
}

12.2.2 Performance

There are no particular performance issues with the solver. GMRES is used
for solving the linear system.

12.2.3 Limitations

Currently many coefficients (such as diffusivity) are not user-definable, they

need to be exposed by the interface.

81
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

12.3 Incompressible Navier–Stokes

Write introduction here, equations etc.

12.3.1 Usage

Present API of solver and give an example.

12.3.2 Performance

Write something about the performance of the solver.

12.3.3 Limitations

Write something about the limitations of the solver.

12.4 Elasticity

Navier’s equations of elasticity with Dirichlet and homogeneous Neumann

boundary conditions:

82
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

u = x − X,
u̇ − v = 0 in Ω0 ,
v̇ − ∇ · σ = f in Ω0 ,
σ = E(u) = E(∇u> + ∇u)
E = λtr()I + 2µ,
v(0, ·) = v 0 , u(0, ·) = u0 in Ω0 ,
u = gD on Γ1 × (0, T ],
−∂n u = 0 on Γ2 × (0, T ]

The variational form:

R R
Ω
v̇w dx = Ω
−σ(u)(v) + f w dx, ∀w. (12.4)

The time integration is done using dG(0) (backward Euler).

R
The mass matrix appearing from Ω v̇wdx is lumped (equivalent to computing
it using nodal quadrature).

12.4.1 Usage

Present API of solver and give an example.

12.4.2 Performance

Write something about the performance of the solver.

12.4.3 Limitations

Write something about the limitations of the solver.

83
Bibliography

[1] Cygwin, 2005. http://cygwin.com/.

[2] GiD, 2005. http://gid.cimne.upc.es/.

[3] Hypre, 2005. http://acts.nersc.gov/hypre/.

[4] MATLAB, 2005. http://www.mathworks.com/.

[5] MayaVi, 2005. http://mayavi.sourceforge.net/.

[6] MEncoder, 2005. http://www.mplayerhq.hu/.

[7] Octave, 2005. http://www.octave.org/.

[8] Open Inventor, 2005. http://http://oss.sgi.com/projects/inventor/ .

[9] OpenDX, 2005. http://www.opendx.org/.

[10] ParaView, 2005. http://www.paraview.org/.

[11] Portable, extensible toolkit for scientific computation petsc, 2005.

http://www-unix.mcs.anl.gov/petsc/petsc-2/.

[12] Tecplot, 2005. http://www.tecplot.com/.

[13] The Visualization Toolkit (VTK), 2005. http://www.vtk.org/.

[14] J. Bey, Tetrahedral grid refinement, Computing, 55 (1995), pp. 355–

378.

85
Appendix A

Reference elements

A.1 The reference triangle

The reference triangle (Figure A.1) is defined by the following three vertices:

v 0 = (0, 0),
v 1 = (1, 0), (A.1)
v 2 = (0, 1).

Note that this corresponds to a counter-clockwise orientation of the vertices

in the plane.

The edges of the reference triangle are ordered following the convention that
edge ei should be opposite to vertex v i for i = 0, 1, 2, with the vertices of
each edge ordered to give a counter-clockwise orientation of the triangle in
the plane:

e0 : (v 1 , v 2 ),
e1 : (v 2 , v 0 ), (A.2)
e2 : (v 0 , v 1 ).

87
 DOLFIN User Manual Hoffman, Jansson, Logg, Wells

x1

v2
v 0 = (0, 0)
v 1 = (1, 0)
PSfrag replacements
v 2 = (0, 1)

x0
v0 v1

Figure A.1: Physical coordinates of the reference triangle.

v2

e1 e0

PSfrag replacements

v0 e2 v1

Figure A.2: Ordering of mesh entities (vertices and edges) for the reference
triangle.

88
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

A.2 The reference tetrahedron

The reference tetrahedron (Figure A.3) is defined by the following four ver-
tices:
v0 = (0, 0, 0),
v1 = (1, 0, 0),
(A.3)
v2 = (0, 1, 0),
v4 = (0, 0, 1).

The faces of the reference tetrahedron are ordered following the convention
that face f i should be opposite to vertex v i for i = 0, 1, 2, 3, with the vertices
of each face ordered to give a counter-clockwise orientation of each face as
seen from the outside of the tetrahedron and the first vertex of face f i given
by vertex v i+1 mod 4 :

f0 : (v 1 , v 3 , v 2 ),
f1 : (v 2 , v 3 , v 0 ),
(A.4)
f2 : (v 3 , v 1 , v 0 ),
f3 : (v 0 , v 1 , v 2 ).

The edges of the reference tetrahedron are ordered following the convention
that edges e0 , e1 , e2 should correspond to the edges of the reference triangle.
Edges e3 , e4 , e5 all ending up at vertex v 3 are ordered based on their first
vertex:
e0 : (v 1 , v 2 ),
e1 : (v 2 , v 0 ),
e2 : (v 0 , v 1 ),
(A.5)
e3 : (v 0 , v 3 ),
e4 : (v 1 , v 3 ),
e5 : (v 2 , v 3 ).

The ordering of vertices on faces implicitly defines an ordering of edges on

89
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

faces by identifying an edge on a face with the opposite vertex on the face:

f0 : (e5 , e0 , e4 ),
f1 : (e3 , e1 , e5 ),
(A.6)
f2 : (e2 , e3 , e4 ),
f3 : (e0 , e1 , e2 ).

Note that the ordering of edges on f 3 is the same as the ordering of edges
on the reference triangle. Also note that the internal ordering of vertices
on edges does not always follow the orientation of the face (which is not
possible).

A.3 Ordering of degrees of freedom

The local and global orderings of degrees of freedom or nodes are obtained
by associating each node with a mesh entity, locally and globally.

A.3.1 Mesh entities

We distinguish between mesh entities of different topological dimensions:

vertices topological dimension 0

edges topological dimension 1
faces topological dimension 2
cells topological dimension 2 or 3

A cell can be either a triangle or a tetrahedron depending on the type of

mesh. For a mesh consisting of triangles, the mesh entities involved are
vertices, edges and cells, and for a mesh consisting of tetrahedrons, the mesh
entities involved are vertices, edges, faces and cells.

90
 DOLFIN User Manual Hoffman, Jansson, Logg, Wells

x2

v3

v 0 = (0, 0, 0)

v 1 = (1, 0, 0)

v 2 = (0, 1, 0)

v 3 = (0, 0, 1)

PSfrag replacements

v2 x1

v0

v1 x0

Figure A.3: Physical coordinates of the reference tetrahedron.

91
 DOLFIN User Manual Hoffman, Jansson, Logg, Wells

v3

PSfrag replacements e3 e5
1
f
f0
f2 e4

v2
e1
v0
f3
e0
2
e

v1

Figure A.4: Ordering of mesh entities (vertices, edges, faces) for the reference
tetrahedron.

92
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

A.3.2 Ordering among mesh entities

With each mesh entity, there can be associated zero or more nodes and the
nodes are ordered locally and globally based on the topological dimension of
the mesh entity with which they are associated. Thus, any nodes associated
with vertices are ordered first and nodes associated with cells last.

If more than one node is associated with a single mesh entity, the internal
ordering of the nodes associated with the mesh entity becomes important, in
particular for edges and faces, where the nodes of two adjacent cells sharing
a common edge or face must line up.

A.3.3 Internal ordering on edges

For edges containing more than one node, the nodes are ordered in the di-
rection from the first vertex (ve0 ) of the edge to the second vertex (ve1 ) of the
edge as in Figure A.5.

ve1

PSfrag replacements
0

ve0

Figure A.5: Internal ordering of nodes on edges.

93
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

A.3.4 Alignment of edges

Depending on the orientation of any given cell, an edge on the cell may be
aligned or not aligned with the corresponding edge on the reference cell if the
vertices of the cell are mapped to the reference cell. We define the alignment
of an edge with respect to a cell to be 0 if the edge is aligned with the
orientation of the reference cell and 1 otherwise.

Example 1: The alignment of the first edge (e0 ) on a triangle is 0 if the

first vertex of the edge is the second vertex (v 1 ) of the triangle.

Example 2: The alignment of the second edge (e1 ) on a tetrahedron is 0 if

the first vertex of the edge is the third vertex (v 2 ) of the tetrahedron.

If two cells share a common edge and the edge is aligned with one of the cells
and not the other, we must reverse the order in which the local nodes are
mapped to global nodes on one of the two cells. As a convention, the order
is kept if the alignment is 0 and reversed if the alignment is 1.

A.3.5 Internal ordering on faces

For faces containing more than one node, the ordering of nodes is nested
going from the first to the third vertex and in each step going from the first
to the second vertex as in Figure A.6.

A.3.6 Alignment of faces

There are six different ways for a face to be aligned on a tetrahedron; there are
three ways to pick the first edge of the face, and once the first edge is picked,
there are two ways to pick the second edge. To define an alignment of faces as
an integer between 0 and 5, we compare the ordering of edges on a face with
the ordering of edges on the corresponding face on the reference tetrahedron.
If the first edge of the face matches the first edge on the corresponding face
on the reference tetrahedron and also the second edge matches the second
edge on the reference tetrahedron, then the alignment is 0. If only the first

94
 DOLFIN User Manual Hoffman, Jansson, Logg, Wells

vf2

PSfrag replacements 5

3 4

0 1 2

vf0 vf1

Figure A.6: Internal ordering of nodes on faces.

95
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

edge matches, then the alignment is 1. We similarly define alignments 2, 3

by matching the first and second edges with the second and third edges on
the corresponding face on the reference tetrahedron, and alignments 4, 5 by
matching the first and second edges with the third and first edges on the
corresponding face on the reference tetrahedron.

Example 1: The alignment of the first face of a tetrahedron is 0 if the first

edge of the face is edge number 5 and the second edge is edge number 0.

Example 2: The alignment of the first face of a tetrahedron is 1 if the first

edge of the face is edge number 5 and the second edge is not edge number 0.
(It must then be edge number 4.)

Example 3: The alignment of the first face of a tetrahedron is 4 if the first

edge of the face is edge number 4 and the second edge is edge number 5.

Example 4: The alignment of the first face of a tetrahedron is 5 if the first

edge of the face is edge number 4 and the second edge is not edge number 5.
(It must then be edge number 0.)

96
Appendix B

Installation

The source code of DOLFIN is portable and should compile on any Unix
system, although it is developed mainly under GNU/Linux (in particular
Debian GNU/Linux). DOLFIN can be compiled under Windows through
Cygwin [1]. Questions, bug reports and patches concerning the installation
should be directed to the DOLFIN mailing list at the address

[email protected]

DOLFIN must currently be compiled directly from source, but effort is under-
way to provide precompiled Debian packages of DOLFIN and other FEniCS
components.

B.1 Installing from source

B.1.1 Dependencies and requirements

DOLFIN depends on a number of libraries that need to be installed on your

system. These libraries include Libxml2 and PETSc. In addition to these

97
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

libraries, you need to install FIAT and FFC if you want to define your own
variational forms.

Installing Libxml2

Libxml2 is a library used by DOLFIN to parse XML data files. Libxml2 can
be obtained from

http://xmlsoft.org/

Packages are available for most Linux distributions. For Debian users, the
package to install is libxml2-dev.

Installing PETSc

PETSc is a library for the solution of linear and nonlinear systems, function-
ing as the backend for the DOLFIN linear algebra classes. DOLFIN depends
on PETSc version 2.3.1 (or 2.3.0), which can be obtained from

http://www-unix.mcs.anl.gov/petsc/petsc-2/

Follow the installation instructions on the PETSc web page. Normally, you
should only have to perform the following simple steps in the PETSc source
directory:

# export PETSC_DIR=‘pwd‘
# ./config/configure.py --with-clanguage=cxx --with-shared=1
# make all

Add --download-hypre=yes to configure.py if you want to install Hypre

which provides a collection of preconditioners, including algebraic multigrid
(AMG).

98
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

DOLFIN assumes that PETSC DIR is /usr/local/lib/petsc/ but this can

be controlled using the flag --with-petsc-dir=<path> when configuring
DOLFIN (see below).

Installing FFC

DOLFIN uses the FEniCS Form Compiler FFC to process variational forms.
FFC can be obtained from

http://www.fenics.org/

Follow the installation instructions given in the FFC manual. FFC follows
the standard for Python packages, which means that normally you should
only have to perform the following simple step in the FFC source directory:

# python setup.py install

Note that FFC depends on FIAT , which in turn depends on the Python pack-
ages Numeric (Debian package python-numeric) and LinearAlgebra (Debian
package python-numeric-ext). Refer to the FFC manual for further details.

B.1.2 Downloading the source code

The latest release of DOLFIN can be obtained as a tar.gz archive in the

download section at

http://www.fenics.org/

Download the latest release of DOLFIN, for example dolfin-0.1.0.tar.gz,

and unpack using the command

99
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

# tar zxfv dolfin-0.1.0.tar.gz

This creates a directory dolfin-0.1.0 containing the DOLFIN source code.

If you want the very latest version of DOLFIN, there is also a version named
dolfin-cvs-current.tar.gz which provides a snapshot of the current CVS
version of DOLFIN, updated automatically from the CVS repository each
hour. This version may contain features not yet present in the latest release,
but may also be less stable and even not work at all.

B.1.3 Compiling the source code

DOLFIN is built using the standard GNU Autotools (Automake, Autoconf),

which means that the installation procedure is simple:

# ./configure
# make

followed by an optional

# make install

to install DOLFIN on your system.

The configure script will check for a number of libraries and try to figure out
how compile DOLFIN against these libraries. The configure script accepts a
collection of optional arguments that can be used to control the compilation
process. A few of these are listed below. Use the command

# ./configure --help

100
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

for a complete list of arguments.

• Use the option --prefix=<path> to specify an alternative directory for

installation of DOLFIN. The default directory is /usr/local/, which
means that header files will be installed under /usr/local/include/
and libraries will be installed under /usr/local/lib/. This option
can be useful if you don’t have root access but want to install DOLFIN
locally on a user account as follows:
# mkdir ~/local
# ./configure --prefix=~/local
# make
# make install

• Use the option --enable-debug to compile DOLFIN with debugging

symbols and assertions.
• Use the option --enable-optimization to compile an optimized ver-
sion of DOLFIN without debugging symbols and assertions.
• Use the option --disable-curses to compile DOLFIN without the
curses interface (a text-mode graphical user interface).
• Use the option --disable-mpi to compile DOLFIN without support
for MPI (Message Passing Interface), assuming PETSc has been com-
piled without support for MPI.
• Use the option --with-petsc-dir=<path> to specify the location of
the PETSc directory. By default, DOLFIN assumes that PETSc has
been installed in /usr/local/lib/petsc/.

Alternatively, use the script configure.local to install DOLFIN in a sub-

directory (local) of the DOLFIN source tree. This can be convenient if you
are not root, don’t want to install DOLFIN on your system, or are working
on several different source trees:

# ./configure.local
# make
# make install

101
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

B.1.4 Compiling the demo programs

After compiling the DOLFIN library according to the instructions above, you
may want to try one of the demo programs in the subdirectory src/demo/
of the DOLFIN source tree. Just enter the directory containing the demo
program you want to compile and type make. You may also compile all demo
programs at once using the command

# make demo

B.1.5 Compiling a program against DOLFIN

Whether you are writing your own Makefiles or using an automated build
system such as GNU Autotools or BuildSystem, it is straightforward to com-
pile a program against DOLFIN. The necessary include and library paths
can be obtained through the script dolfin-config which is automatically
generated during the compilation of DOLFIN and installed in the bin sub-
directory of the <path> specified with --prefix. Assuming this directory is
in your executable path (environment variable PATH), the include path for
building DOLFIN can be obtained from the command

# dolfin-config --cflags

and the path to DOLFIN libraries can be obtained from the command

# dolfin-config --libs

If dolfin-config is not in your executable path, you need to provide the

full path to dolfin-config.

Examples of how to write a proper Makefile are provided with each of the
example programs in the subdirectory src/demo/ in the DOLFIN source
tree.

102
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

B.2 Debian package

In preparation.

B.3 Installing from source under Windows

DOLFIN can be used under Windows using Cygwin, which provides a Linux-
like environment. The installation process is largely the same as under
GNU/Linux. This section addresses some Cygwin specific issues.

To use DOLFIN under Cygwin, the Cygwin development tools must be in-
stalled. Instructions for installing PETSc under Cygwin can be found on
the PETSc web page. Installation of FFC and FIAT is the same as under
GNU/Linux. The Python package Numeric is not available as a Cygwin
package and must be installed manually. To compile DOLFIN, the Cygwin
package libxml2-devel must be installed. DOLFIN does not link correctly
with the curses libraries of Cygwin, so under Cygwin, DOLFIN can be built
by:

# ./configure --disable-curses
# make

If MPI has not been installed:

# ./configure --disable-mpi --disable-curses

# make

Due to problems with the latest GCC compilers provided by Cygwin (GCC
3.4.4), compiling DOLFIN will lead to fatal errors. These problems can be
avoided by using GCC version 3.3.3 provided by Cygwin.

103
Appendix C

Contributing code

If you have created a new module, fixed a bug somewhere, or have made a
small change which you want to contribute to DOLFIN, then the best way to
do so is to send us your contribution in the form of a patch. A patch is a file
which describes how to transform a file or directory structure into another.
The patch is built by comparing a version which both parties have against
the modified version which only you have.

C.1 Creating a patch

The tool used to create a patch is called diff and the tool used to apply
the patch is called patch. These tools are free software and are standard on
most Unix systems.

Here’s an example of how it works. Start from the latest release of DOLFIN,
which we here assume is release 0.1.0. You then have a directory structure
under dolfin-0.1.0 where you have made modifications to some files which
you think could be useful to other users.

1. Clean up your modified directory structure to remove temporary and

binary files which will be rebuilt anyway:

105
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

# make clean

2. From the parent directory, rename the DOLFIN directory to something

else:

# mv dolfin-0.1.0 dolfin-0.1.0-mod

3. Unpack the version of DOLFIN that you started from:

# tar zxfv dolfin-0.1.0.tar.gz

4. You should now have two DOLFIN directory structures in your current
directory:

# ls
dolfin-0.1.0
dolfin-0.1.0-mod

5. Now use the diff tool to create the patch:

# diff -u --new-file --recursive dolfin-0.1.0

dolfin-0.1.0-mod > dolfin-<identifier>-<date>.patch

written as one line, where <identifier> is a keyword that can be used

to identify the patch as coming from you (your username, last name,
first name, a nickname etc) and <date> is today’s date in the format
yyyy-mm-dd.

6. The patch now exists as dolfin-<identifier>-<date>.patch and

can be distributed to other people who already have dolfin-0.1.0 to
easily create your modified version. If the patch is large, compressing
it with for example gzip is advisable:

# gzip dolfin-<identifier>-<date>.patch

106
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

C.2 Sending patches

Patch files should be sent to the DOLFIN mailing list at the address

[email protected]

Include a short description of what your patch accomplishes. Small patches

have a better chance of being accepted, so if you are making a major con-
tribution, please consider breaking your changes up into several small self-
contained patches if possible.

C.3 Applying a patch (maintainers)

Let’s say that a patch has been built relative to DOLFIN release 0.1.0. The
following description then shows how to apply the patch to a clean version
of release 0.1.0.

1. Unpack the version of DOLFIN which the patch is built relative to:

# tar zxfv dolfin-0.1.0.tar.gz

2. Check that you have the patch dolfin-<identifier>-<date>.patch

and the DOLFIN directory structure in the current directory:

# ls
dolfin-0.1.0
dolfin-<identifier>-<date>.patch

Unpack the patch file using gunzip if necessary.

3. Enter the DOLFIN directory structure:

# cd dolfin-0.1.0

107
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

4. Apply the patch:

# patch -p1 < ../dolfin-<identifier>-<date>.patch

The option -p1 strips the leading directory from the filename references
in the patch, to match the fact that we are applying the patch from
inside the directory. Another useful option to patch is --dry-run
which can be used to test the patch without actually applying it.

5. The modified version now exists as dolfin-0.1.0.

C.4 License agreement

By contributing a patch to DOLFIN, you agree to license your contributed

code under the GNU General Public License (a condition also built into
the GPL license of the code you have modified). Before creating the patch,
please update the author and date information of the file(s) you have modified
according to the following example:

// Copyright (C) 2004-2005 Johan Hoffman and Anders Logg.

// Licensed under the GNU GPL Version 2.
//
// Modified by Johan Jansson 2005.
// Modified by Garth N. Wells 2005.
//
// First added: 2004-06-22
// Last changed: 2005-09-01

As a rule of thumb, the original author of a file holds the copyright.

108
Appendix D

License

DOLFIN is licensed under the GNU General Public License (GPL) version
2, included verbatim below.

GNU GENERAL PUBLIC LICENSE

Version 2, June 1991

Copyright (C) 1989, 1991 Free Software Foundation, Inc.

59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.

Preamble

The licenses for most software are designed to take away your
freedom to share and change it. By contrast, the GNU General Public
License is intended to guarantee your freedom to share and change free
software--to make sure the software is free for all its users. This
General Public License applies to most of the Free Software
Foundation’s software and to any other program whose authors commit to
using it. (Some other Free Software Foundation software is covered by
the GNU Library General Public License instead.) You can apply it to
your programs, too.

When we speak of free software, we are referring to freedom, not

price. Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for

109
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

this service if you wish), that you receive source code or can get it
if you want it, that you can change the software or use pieces of it
in new free programs; and that you know you can do these things.

To protect your rights, we need to make restrictions that forbid

anyone to deny you these rights or to ask you to surrender the rights.
These restrictions translate to certain responsibilities for you if you
distribute copies of the software, or if you modify it.

For example, if you distribute copies of such a program, whether

gratis or for a fee, you must give the recipients all the rights that
you have. You must make sure that they, too, receive or can get the
source code. And you must show them these terms so they know their
rights.

We protect your rights with two steps: (1) copyright the software, and
(2) offer you this license which gives you legal permission to copy,
distribute and/or modify the software.

Also, for each author’s protection and ours, we want to make certain
that everyone understands that there is no warranty for this free
software. If the software is modified by someone else and passed on, we
want its recipients to know that what they have is not the original, so
that any problems introduced by others will not reflect on the original
authors’ reputations.

Finally, any free program is threatened constantly by software

patents. We wish to avoid the danger that redistributors of a free
program will individually obtain patent licenses, in effect making the
program proprietary. To prevent this, we have made it clear that any
patent must be licensed for everyone’s free use or not licensed at all.

The precise terms and conditions for copying, distribution and

modification follow.

GNU GENERAL PUBLIC LICENSE

TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

0. This License applies to any program or other work which contains

a notice placed by the copyright holder saying it may be distributed
under the terms of this General Public License. The "Program", below,
refers to any such program or work, and a "work based on the Program"
means either the Program or any derivative work under copyright law:
that is to say, a work containing the Program or a portion of it,
either verbatim or with modifications and/or translated into another

110
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

language. (Hereinafter, translation is included without limitation in

the term "modification".) Each licensee is addressed as "you".

Activities other than copying, distribution and modification are not

covered by this License; they are outside its scope. The act of
running the Program is not restricted, and the output from the Program
is covered only if its contents constitute a work based on the
Program (independent of having been made by running the Program).
Whether that is true depends on what the Program does.

1. You may copy and distribute verbatim copies of the Program’s

source code as you receive it, in any medium, provided that you
conspicuously and appropriately publish on each copy an appropriate
copyright notice and disclaimer of warranty; keep intact all the
notices that refer to this License and to the absence of any warranty;
and give any other recipients of the Program a copy of this License
along with the Program.

You may charge a fee for the physical act of transferring a copy, and
you may at your option offer warranty protection in exchange for a fee.

2. You may modify your copy or copies of the Program or any portion
of it, thus forming a work based on the Program, and copy and
distribute such modifications or work under the terms of Section 1
above, provided that you also meet all of these conditions:

a) You must cause the modified files to carry prominent notices

stating that you changed the files and the date of any change.

b) You must cause any work that you distribute or publish, that in
whole or in part contains or is derived from the Program or any
part thereof, to be licensed as a whole at no charge to all third
parties under the terms of this License.

c) If the modified program normally reads commands interactively

when run, you must cause it, when started running for such
interactive use in the most ordinary way, to print or display an
announcement including an appropriate copyright notice and a
notice that there is no warranty (or else, saying that you provide
a warranty) and that users may redistribute the program under
these conditions, and telling the user how to view a copy of this
License. (Exception: if the Program itself is interactive but
does not normally print such an announcement, your work based on
the Program is not required to print an announcement.)

111
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

These requirements apply to the modified work as a whole. If

identifiable sections of that work are not derived from the Program,
and can be reasonably considered independent and separate works in
themselves, then this License, and its terms, do not apply to those
sections when you distribute them as separate works. But when you
distribute the same sections as part of a whole which is a work based
on the Program, the distribution of the whole must be on the terms of
this License, whose permissions for other licensees extend to the
entire whole, and thus to each and every part regardless of who wrote it.

Thus, it is not the intent of this section to claim rights or contest

your rights to work written entirely by you; rather, the intent is to
exercise the right to control the distribution of derivative or
collective works based on the Program.

In addition, mere aggregation of another work not based on the Program

with the Program (or with a work based on the Program) on a volume of
a storage or distribution medium does not bring the other work under
the scope of this License.

3. You may copy and distribute the Program (or a work based on it,
under Section 2) in object code or executable form under the terms of
Sections 1 and 2 above provided that you also do one of the following:

a) Accompany it with the complete corresponding machine-readable

source code, which must be distributed under the terms of Sections
1 and 2 above on a medium customarily used for software interchange; or,

b) Accompany it with a written offer, valid for at least three

years, to give any third party, for a charge no more than your
cost of physically performing source distribution, a complete
machine-readable copy of the corresponding source code, to be
distributed under the terms of Sections 1 and 2 above on a medium
customarily used for software interchange; or,

c) Accompany it with the information you received as to the offer

to distribute corresponding source code. (This alternative is
allowed only for noncommercial distribution and only if you
received the program in object code or executable form with such
an offer, in accord with Subsection b above.)

The source code for a work means the preferred form of the work for
making modifications to it. For an executable work, complete source
code means all the source code for all modules it contains, plus any
associated interface definition files, plus the scripts used to

112
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

control compilation and installation of the executable. However, as a

special exception, the source code distributed need not include
anything that is normally distributed (in either source or binary
form) with the major components (compiler, kernel, and so on) of the
operating system on which the executable runs, unless that component
itself accompanies the executable.

If distribution of executable or object code is made by offering

access to copy from a designated place, then offering equivalent
access to copy the source code from the same place counts as
distribution of the source code, even though third parties are not
compelled to copy the source along with the object code.

4. You may not copy, modify, sublicense, or distribute the Program

except as expressly provided under this License. Any attempt
otherwise to copy, modify, sublicense or distribute the Program is
void, and will automatically terminate your rights under this License.
However, parties who have received copies, or rights, from you under
this License will not have their licenses terminated so long as such
parties remain in full compliance.

5. You are not required to accept this License, since you have not
signed it. However, nothing else grants you permission to modify or
distribute the Program or its derivative works. These actions are
prohibited by law if you do not accept this License. Therefore, by
modifying or distributing the Program (or any work based on the
Program), you indicate your acceptance of this License to do so, and
all its terms and conditions for copying, distributing or modifying
the Program or works based on it.

6. Each time you redistribute the Program (or any work based on the
Program), the recipient automatically receives a license from the
original licensor to copy, distribute or modify the Program subject to
these terms and conditions. You may not impose any further
restrictions on the recipients’ exercise of the rights granted herein.
You are not responsible for enforcing compliance by third parties to
this License.

7. If, as a consequence of a court judgment or allegation of patent

infringement or for any other reason (not limited to patent issues),
conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License. If you cannot
distribute so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you

113
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

may not distribute the Program at all. For example, if a patent

license would not permit royalty-free redistribution of the Program by
all those who receive copies directly or indirectly through you, then
the only way you could satisfy both it and this License would be to
refrain entirely from distribution of the Program.

If any portion of this section is held invalid or unenforceable under

any particular circumstance, the balance of the section is intended to
apply and the section as a whole is intended to apply in other
circumstances.

It is not the purpose of this section to induce you to infringe any

patents or other property right claims or to contest validity of any
such claims; this section has the sole purpose of protecting the
integrity of the free software distribution system, which is
implemented by public license practices. Many people have made
generous contributions to the wide range of software distributed
through that system in reliance on consistent application of that
system; it is up to the author/donor to decide if he or she is willing
to distribute software through any other system and a licensee cannot
impose that choice.

This section is intended to make thoroughly clear what is believed to

be a consequence of the rest of this License.

8. If the distribution and/or use of the Program is restricted in

certain countries either by patents or by copyrighted interfaces, the
original copyright holder who places the Program under this License
may add an explicit geographical distribution limitation excluding
those countries, so that distribution is permitted only in or among
countries not thus excluded. In such case, this License incorporates
the limitation as if written in the body of this License.

9. The Free Software Foundation may publish revised and/or new versions
of the General Public License from time to time. Such new versions will
be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.

Each version is given a distinguishing version number. If the Program

specifies a version number of this License which applies to it and "any
later version", you have the option of following the terms and conditions
either of that version or of any later version published by the Free
Software Foundation. If the Program does not specify a version number of
this License, you may choose any version ever published by the Free Software
Foundation.

114
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

10. If you wish to incorporate parts of the Program into other free
programs whose distribution conditions are different, write to the author
to ask for permission. For software which is copyrighted by the Free
Software Foundation, write to the Free Software Foundation; we sometimes
make exceptions for this. Our decision will be guided by the two goals
of preserving the free status of all derivatives of our free software and
of promoting the sharing and reuse of software generally.

NO WARRANTY

11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY

FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
REPAIR OR CORRECTION.

12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING

WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.

END OF TERMS AND CONDITIONS

115
Index

File, 57 diff, 105

Progress, 69 downloading, 15, 99
add(), 75
cout, 65 eigenvalue solver, 27
dolfin assert(), 67 enumeration, 12
dolfin begin(), 68 errors, 66
dolfin debug(), 67 FEniCS, 13
dolfin end(), 68 FFC, 99
dolfin error(), 66 ffc, 17
dolfin info(), 65 FIAT, 99
dolfin log(), 70 file formats, 59
dolfin output(), 70 finite element method, 13
dolfin warning(), 66 Function, 33
endl, 65 functions, 33
get(), 73
set(), 74 GNU General Public License, 109
GPL, 109
assertions, 67
automation, 13 I/O, 57
incompressible Navier–Stokes, 82
compiling, 100, 102 indices, 12
contact, 12 input/output, 57
contributing, 105 installation, 15, 97
convection–diffusion, 80
Libxml2, 98
curses interface, 70
license, 108, 109
Cygwin, 103
log system, 65
Debian package, 103 MayaVi, 36
debugging, 67
demo programs, 102 Navier–Stokes, 82
dependencies, 97 Newton’s method, 53, 55

117
DOLFIN User Manual Hoffman, Jansson, Logg, Wells

NewtonSolver, 55
nonlinear solver, 53
NonlinearFunction, 53

object, 57
output destination, 70

parameters, 73
ParaView, 36
partial differential equations, 45
patch, 105, 107
PETSc, 98
Poisson’s equation, 16, 78
post-processing, 57
pre-processing, 57
progress bar, 69

quickstart, 15

reference tetrahedron, 89
reference triangle, 87

source code, 99

tasks, 68
typographic conventions, 11

user-defined functions, 39

warnings, 66

XML, 59, 76

118