Frequently asked questions

A list of FAQs which didn't find their way into this list can be found in the Bug Tracking System.

General

How should I cite DUNE?

If you are using the dune-grid module, please cite the following publications.

• P. Bastian, M. Blatt, A. Dedner, C. Engwer, R. Klöfkorn, M. Ohlberger, O. Sander. A Generic Grid Interface for Parallel and Adaptive Scientific Computing. Part I: Abstract Framework. Computing, 82(2-3), 2008, pp. 103-119. Preprint
• P. Bastian, M. Blatt, A. Dedner, C. Engwer, R. Klöfkorn, R. Kornhuber, M. Ohlberger, O. Sander. A Generic Grid Interface for Parallel and Adaptive Scientific Computing. Part II: Implementation and Tests in DUNE. Computing, 82(2-3), 2008, pp. 121-138. Preprint

If you used the dune-istl module for solving your linear equation systems, please cite at least the first of the following publications. If you performed parallel computation, please cite both of the following publications.

• M. Blatt, P. Bastian. The Iterative Solver Template Library. In B. Kåström, E. Elmroth, J. Dongarra and J. Wasniewski, Applied Parallel Computing. State of the Art in Scientific Computing. Volume 4699 of Lecture Notes in Scientific Computing, pages 666-675. Springer, 2007. PDF-Preprint (149K)
• P. Bastian, M. Blatt. On the Generic Parallelisation of Iterative Solvers for the Finite Element Method In Int. J. Computational Science and Engineering,4(1):56-69, 2008. PDF - Preprint (229K)

How do I access the download directory on the web server?

Mount https://www.dune-project.org/download/ using your favorite webdav client. Username und Password are the same as for the svn.

Why does DUNE not use boost?

We are trying to avoid hard dependencies of the core modules on external libraries. The reason is that software installations on really big supercomputers tend to be very old. Often the software is installed at the same time the supercomputer is built and essentially never updated. There is a good chance that there is no (recent enough) version of Boost installed.

The reasons for that are manifold. Often the software installation on a supercomputer is very special and updating the software may require coorperation from the manufacturer. Supercomputers are used by a lot of people and downtime can cost a lot; updating software or even installing new software always brings the risk that something goes wrong.

If we introduce a hard dependency on Boost in one of the core modules, Dune will not work without Boost present. Every Dune user is forced to install Boost first if it is not present on the computer he or she wants to run the computations on.

But don't despair---even without a dependency on Boost, you can still use Dune and Boost together perfectly. The difference is that we don't force you to do so.

Installation/Compilation

How do I start my own project?

First you have to get DUNE itself. This is explained in the installation notes. Then use the Dune project generator to create a simple application framework. This is done by going to where you want your application to be, and typing

   dune-common/bin/duneproject

The program will ask you for a project name, an initial version number and a maintainer's email. Supply all this and you get a new directory named after your project. In the directory you will find a sample .cc-file, the necessary AutoTools infrastructure and a README which tells you how to proceed from there.

configure fails if no f77 compiler is found.

If there is no fortran compiler installed, configure should work. If this is not the case, please reopen bug #185.

Problems occur, if there is a fortran compiler installed but it does not match the C-compiler you are using (e.g. icc together with g77), because the tests try to link fortran from C, which cannot work.

A workaround (and crude hack) is to set F77=true. In this case the test sees that it cannot compile any fortran code and just warns about it.

What software do I need to use DUNE?

In order to build Dune you need at least the following software:

• a standard compliant C++ compiler [ tested are g++ (>= 3.4.1) and icc (7.0, 8.0 and 9.0)]
• pkg-config

When building the development version of Dune you will also need

• automake (>= 1.5)
• autoconf (>= 2.50)
• libtool

This will provide you with the core Dune features. The different grid managers like Alberta or UG have to be downloaded separately.

Why do I get so many warning about violated strict-aliasing?

Dune violates strict-aliasing.

You have to compile Dune will the the option "-fno-strict-aliasing". Newer versions of g++ make more use of strict aliasing rules. If you don't use the "-fno-strict-aliasing" option, you will receive many warnings, and you might even observe undesired results and unreproducible errors.

But we are not alone with this problem. Several software projects intentionally violate strict-aliasing. For example, Python 2.x did so to implement reference counting ( http://mail.python.org/pipermail/python-dev/2003-July/036898.html). The Linux kernel does this because strict aliasing causes problems with optimization of inlined code ( http://lkml.org/lkml/2003/2/26/158).

For more information see Flyspray task #674

How do I set my favourite compiler options with this fancy build-system?

You can find information about this in the build system documentation

Can I use DUNE on a Windows System?

All DUNE development is currently done on Unix-like machines. For Windows you need a small set of patches. Please inquire on the mailing list. Be aware that we do not support Windows officially. This might result in larger response times and less ambitious feedback on the list.

Why are the wrong libs used on my multilib architecture system (e.g. x86_64)

Some architectures are designed, such that either 64bit or 32bit libraries can be used. The most wide spread systems are x86_64 systems, like AMD Opteron or Intel Core 2. Obviously, the program has to be compiled either as a 64bit or a 32bit binary.

If you are using libtool in version < 2, libtool can not handle different architectures. In case you have 32bit and 64bit libs installed on your system, it may happen that libtool mixes 32bit and 64bit libraries.

You can upgrade to libtool 2.x. This should fix your problems.

How do I use the make headercheck feature?

make headercheck compiles all headers in your modules separately and thus checks whether they include all headers they need. There are two options to 'make headercheck':

• SILENT=[0|1] - 0 = show the compiler output
• HEADER=headerfile - consider only headerfile

The default behaviour is SILENT=(HEADER == "").

An example usages would be

1. make SILENT=0 headercheck
2. make SILENT=1 headercheck
3. make SILENT=0 HEADER=common/fvector.hh headercheck
4. make SILENT=1 HEADER=common/fvector.hh headercheck
5. make HEADER=common/fvector.hh

Example 1 behaves exactly like 'make headercheck' and example 4 behaves exactly like example 5.

Another interesting feature is to use make's ability to ignore errors. A good start for the headercheck is this:

  make -is headercheck

This way, all files are checked and you can see which ones have errors. Then, you can use

  make -is HEADER=headerfile headercheck

to find out what is actually wrong.

If you prefer the headercheck to stop at the first error and give output, you might consider

  make -s SILENT=0 headercheck

The Grid Interface

Does a Grid Implementation Have to Provide Entities of all Codimensions?

The DUNE grid interface contains methods for access to grid entities of all codimensions. However, for some entities such as faces and edges in a 3d grid, this is sometimes difficult to implement. Also, most PDE codes will not need them anyways. Therefore, currently grid implementations are only required to provide vertices and elements. All others are optional. Please refer to the documentation for the individual grids to see what codimensions they implement.

Lagrangian finite elements of order higher than one have degrees of freedom on edges and faces. In order to implement them you don't need the actual entities, just getting their indices is enough. Therefore, the method subIndex<codim>() of IndexSet is required to be implemented for all codimensions.

Is There a Way to Organize a Grid in Separate Subdomains?

Some grid managers assign a domain id to each element. Using this id the grid can be viewed as consisting of several subdomains. Each subdomain can then, for example, have different material properties. Currently the DUNE grid interface does not contain this concept. There has been discussion about including it but so far nothing happened.

One reason for this omission is that the functionality is not strictly necessary. An element's domain id is element data just like a piecewise constant FE function. You can maintain a vector with the element ids in your application and feed it to your problem assembler to let it choose your material parameters correctly. Update: This mechanism has been implemented as the Dune meta grid MultiDomainGrid.

How do I implement my own DUNE grid?

Unfortunately, so far there is no text on how to implement your own grid manager using the DUNE interface. There is some example code, though. Download the module dune-grid-dev-howto. There, you'll find the implementation of IdentityGrid, which does nothing more than wrap another DUNE grid. It therefore already contains all the boilerplate code that you will need. Copy & paste this grid and add your own functionality!

Can I access Entities/EntityPointers by index?

No, this is not directly possible using the grid interface. The reason is that this cannot be implemented efficiently for some unstructured grid managers, hence you should not rely on it. In most cases you can restructure your code to use iterators and access your data using indices instead.

If you absolutely need random access you can store EntitySeeds (development branch and future dune versions ≥ 2.1) in a container and use them to create EntityPointers if you need access to the corresponding Entity. EntitySeeds are intended to use as little memory as possible while allowing quick access to Entities. Notice, that some grids use the default implementations of EntitySeed which internally is an EntityPointer (see below).

In dune versions before 2.1 you can store EntityPointers instead and compactify them to reduce their memory usage. However they might still need a lot of memory.

There has been some discussion whether access by indices should be allowed for structured grids.

How can I access the id of an Intersection?

Only entities have ids. Intersections are not entities!

All grids have entities of codimension dim (vertices) and codimension 0 (elements), and all have intersections. Some grids have entities of other codimensions as well. Even if a grid has entities of codimension 1, these are not the same as entities. The most obvious differences are:

• Intersections know the neighbouring cells, codim 1 entities don't.
• Intersections have an orientation, codim 1 entities don't.
• Codim 1 entities have indices and ids and can be used to obtain array indices from a mapper (even if the grid does not support codim 1 entity objects!) For intersections, indices, id's and maps are not provided by core Dune, though it is possibly to build such things yourself.

• In non-conforming grids you may have the following situation:

  

  Elements b, c, d and e all have four codim 1 subentities and four corresponding intersections. Element a also has four codim 1 subentities, but it has five intersections. The codim 1 entity to the right of b is the same as the codim 1 entity to the left of d. You have three codim 1 entities to the right of a however: one covering the whole of a's right border, and two smaller ones each covering the upper and the lower half of a's border, respectively.

If you know you have a conforming grid, you have a correspondence between intersections and codim 1 entities (ignoring the orientation of the intersections). In that case you can usually get away by using the id of the corresponding codim 1 entity as the id of the intersection (even if the grid does not support codim 1 entities as independent objects. Use

    grid.globalIdSet().subId(e, i.indexInInside(), 1);

where i is the intersection and e is the codim 0 entity i was obtained from. If you don't have e readily available, you can use

    grid.globalIdSet().subId(*i.inside(), i.indexInInside(), 1);

instead.

Core Grid Implementations

Why does UGGrid run out of memory way before my physical memory is exhausted?

When working with UGGrid you may experience crashes with a message

   ERROR in low/heaps.c/GetFreelistMemory: not enough memory for 40 bytes.
   ERROR in low/heaps.c/GetFreelistMemory: not enough memory for 40 bytes.
   uggridtest: heaps.c:647: void* UG::GetFreelistMemory(UG::HEAP*, UG::INT): Assertion `0' failed.

even though you expect your machine to have sufficient main memory. The reason for this lies in the design of the UG grid manager. UG implements its own memory management. When creating a grid, a certain quantity of memory is allocated once, and used for all subsequent grid operations. If this quantity of memory is exhausted you get the error message above.

The default memory size is set to 500MB per grid. You can set it to other values by using the UGGrid constructor

   UGGrid (unsigned int heapSize=500);

Starting with Dune-2.1 / dune-grid revision 7100, you can set the default heap size by calling the static method

   void UGGrid::setDefaultHeapSize(unsigned int);

This is now the preferred way, and it is the only way when you don't call the grid constructor yourself (because for example a file reader does it for you). The special constructor may actually disappear in future versions of Dune.

Why is setting up a UGGrid coarse grid with more then 100000 nodes so extremely slow?

UG switches from a fast, but memory-intensive implementation to a slower one, as soon as your grid exceeds a certain size. By default, this size is set to 100000 nodes. If you need to handle more nodes you can change the value of NDELEM_BLKS_MAX in the file my-ug-directory/gm/gm.h. The value gives the largest number of nodes handled with the fast algorithm, divided by 1000. Don't forget to rebuild UG afterwards. If you link statically against UG you also have to rebuild dune-grid.

Why does globalRefine() sometimes segfault for AlbertaGrid<3>?

This is a known issue with ALBERTA. The segfault you experience is a actually a stack overflow during the recursive bisection algorithm. When trying to refine an element, ALBERTA tries to use a prescribed refinement edge. It tries to refine all elements that share this edge (called a refinement patch) at the same time. But this edge need not be a refinement edge for the other elements in the patch. Therefore, ALBERTA tries to recursively refine such an element before refining the current patch. This way, one can run into cycles. While ALBERTA can ensure that the recursive bisection terminates in 2d, no such algorithm is known in 3d. One has to rely on heuristics to solve this problem. A simple idea is to select the longest edge for refinement on the macro grid. If this edge is unique, it makes the algorithm terminate in 2d. In 3d, this works unless an element is refined more that once. By default, the GridFactory for AlbertaGrid does not modify the grid. There are two reasons for this:

• We don't know any reliable algorithm (not even heuristically) to make the bisection terminate in 3d. A simple idea is to select the longest edge for refinement on the macro grid, which works in 2d in general. But in 3d this does not necessarily work.
• In 2d ALBERTA handles this problem by itself (and 1d is trivial)
• Changing the refinement edge can result in a less local refinement (longest-edge bisection is known to produce very non-local refinements.

We can give you two hints, though:

• As long as you want to triangulate cube grids the DGF parser will split it into tetrahedra that ALBERTA can handle.
• The refinement edge in ALBERTA is always between vertices 0 and 1.

Why does adapt() on ALUGrid sometimes lead to a failing assertion?

The ALUGrid library keeps track of open iterators. Since these become invalid during adaptation, ALUGrid asserts that no dangling iterators exist. This can be avoided using -DNDEBUG in the compile flags for the ALUGrid library (which is recommended in any case).

The Iterative Solver Template Library (ISTL)

I am getting weird segmentation faults using the parallel solvers with OpenMPI

Unfortunately there is a bug in OpenMPI (version < 1.3.2) that prevents ISTL from setting up the parallel distribution information correctly. Please either use a newer version of OpenMPI or try MPICH or LAM.