Iterator ranges for entities and intersections to support iteration with range-based for loops. More...

Common entity ranges
Entity ranges for common entity types. If in doubt, use one of these.
template<typename GV >
IteratorRange<... >	elements (const GV &gv)
	Iterates over all elements / cells (entities with codimension 0) of a GridView. More...

template<typename GV >
IteratorRange<... >	facets (const GV &gv)
	Iterates over all facets (entities with codimension 1) of a GridView. More...

template<typename GV >
IteratorRange<... >	edges (const GV &gv)
	Iterates over all edges (entities with dimension 1) of a GridView. More...

template<typename GV >
IteratorRange<... >	vertices (const GV &gv)
	Iterates over all vertices (entities with dimension 0) of a GridView. More...

Intersection Range
Iterator range for intersections .
template<typename GV , typename Entity >
IteratorRange<... >	intersections (const GV &gv, const Entity &e)
	Iterates over all Intersections of an Entity with respect to the given GridView. More...

Hierarchic Entity range
Iterator range for hierarchic access to the more-refined entities that result from the subdivision of a given element.
template<typename Entity >
IteratorRange<... >	descendantElements (const Entity &e, int maxLevel)
	Iterates over all descendant elements of the given element up to a maximum level. More...

Entity ranges with (co)dimension template argument
Entity ranges which allow specifying the codimension / dimension as a numeric template parameter.
template<typename GV , int codim>
IteratorRange<... >	entities (const GV &gv, Codim< codim > cd)
	Iterates over all entities of a GridView with the given codimension. More...

template<typename GV , int dim>
IteratorRange<... >	entities (const GV &gv, Dim< dim > d)
	Iterates over all entities of a GridView with the given dimension. More...

Common entity ranges for non-standard parallel partitions
The following Entity ranges make it possible to specify a PartitionSet which is sometimes needed in parallel code.
template<typename GV , unsigned int partitions>
IteratorRange<... >	elements (const GV &gv, PartitionSet< partitions > ps)
	Iterates over all elements / cells (entities with codimension 0) of a GridView that belong to the given PartitionSet. More...

template<typename GV , unsigned int partitions>
IteratorRange<... >	facets (const GV &gv, PartitionSet< partitions > ps)
	Iterates over all facets (entities with codimension 1) of a GridView that belong to the given PartitionSet. More...

template<typename GV , unsigned int partitions>
IteratorRange<... >	edges (const GV &gv, PartitionSet< partitions > ps)
	Iterates over all edges (entities with dimension 1) of a GridView that belong to the given PartitionSet. More...

template<typename GV , unsigned int partitions>
IteratorRange<... >	vertices (const GV &gv, PartitionSet< partitions > ps)
	Iterates over all vertices (entities with dimension 0) of a GridView that belong to the given PartitionSet. More...

Generic entity ranges for non-standard parallel partitions
These Entity ranges allow for the maximum flexibility; they are parameterized on both the co(cimension) and the parallel PartitionSet.
template<typename GV , int codim, unsigned int partitions>
IteratorRange<... >	entities (const GV &gv gv, Codim< codim > cd, PartitionSet< partitions > ps)
	Iterates over all entities of a GridView with the given codimension that belong to the given PartitionSet. More...

template<typename GV , int dim, unsigned int partitions>
IteratorRange<... >	entities (const GV &gv, Dim< dim > d, PartitionSet< partitions > ps)
	Iterates over all entities of a GridView with the given dimension that belong to the given PartitionSet. More...

Detailed Description

Iterator ranges for entities and intersections to support iteration with range-based for loops.

Iterating over sets of entities or intersections is one of the most common operations when writing DUNE code. The grid interface implements this in the standard C++ ways by providing iterators and matching begin() and end() methods, but their usage can be rather unwieldy.

This page describes a much simpler alternative based on a C++11 feature called range-based for loop.

Range-based for loop

A range-based for loop is a short-hand way of iterating over any object that provides the standard begin() and end() methods. It looks like this:

for (const auto& i : vec)

i *= 2;

This code will multiply all entries of vec by 2. The loop head always looks like for (<type> <variable-name> : <container>). You can also specify the exact type of the variable, but it is normally much easier to let the compiler do that for you using auto.

Note: We are aware that people like Bjarne Stroustrup and Herb Sutter advertise the use auto&&. Sadly GCC prior to version 6 has a bug (see https://gcc.gnu.org/bugzilla/show_bug.cgi?id=63506), which prevents the use of auto&& in template functions. For this reason we currently advice the use of const auto&.

For those interested in the technical details, the compiler has translated the loop into something resembling this (not quite, but we'll forget about the minor details here):

for (auto it = vec.begin(),
       end = vec.end();
     it != end;
     ++it)
{
  const auto& i = *it;
  i *= 2;
}

For further details, see e.g. http://en.cppreference.com/w/cpp/language/range-for.

Entities

You cannot simply iterate over all entities of a GridView by passing it to a range-based for loop, simply because you cannot (and probably do not want to) iterator over all of its entities. Instead, algorithms typically have to iterate over all entities with a particular codimension, e.g. over all grid cells. The functions listed at the top of this page allow you to do just this. Assuming you have a GridView gv, you can iterate over its cells and vertices like this:

// iterate over cells
for (const auto& cell : elements(gv))
{
  std::cout << "Cell " << gv.indexSet().index(cell) << " is centered at "
            << cell.geometry().center() << std::endl;
}
// iterate over vertices
for (const auto& vertex : vertices(gv))
{
  std::cout << "Vertex " << gv.indexSet().index(vertex) << " at "
            << vertex.geometry().center() << std::endl;
}

Note: As explained above, always use const auto& for the type of the Entity!

There are also functions for iterating over facets() and edges() as well as generic entities() functions, which allow you to specify a numeric codimension or dimension.

If you are using Dune for parallel computations, you probably know that the GridView offers iterators with different PartitionIteratorTypes. Those are also supported with range-based for loops: By default, the functions above will iterate over all entities (Dune::All_Partition), but they accept an additional parameter for selecting a different set of partitions. This parameter is of type Dune::PartitionSet. You can find pre-instantiated objects for all partitions and allowed combinations in the namespace Dune::Partitions. Using those objects, you can iterate over all interior and border vertices like this:

// use prebuild PartitionSet
for (const auto& vertex : vertices(gv,Dune::Partitions::interiorBorder))
{
   ...
}
// construct PartitionSet by combining partitions
for (const auto& vertex : vertices(gv,Dune::Partitions::interior + Dune::Partitions::border))
{
   ...
}

Intersections

If you want to iterate over the intersections of an Entity, you can use the function intersections() to obtain a range that is suitable for a range-based for loop. Intersections are always defined with respect to a GridView; for further information, see the discussion on locally refined grids.

As an example, the following code counts the number of boundary intersections for a given GridView gv:

std::size_t count = 0;
for (const auto& e : elements(gv))
{
  do_stuff();
  for (const auto& i : intersections(gv,e))
  {
    if (e.boundary())
      ++count;
  }
}

Information for grid implementors

Custom range implementations

The default implementation of the range generator functions calls the correct begin() and end() methods on the GridView / the Entity and stores the iterators returned by these methods in an IteratorRange object which is then returned by value (as a temporary object). While any overhead associated with this process will normally be negligible compared with the ensuing grid traversal, you can guarantee optimal performance by making sure that your iterators are move-constructible and move-assignable. If, for some reason, you don't want to rely on this default implementation, you only have to provide an overload for the function entities(const GV&, Dune::Codim<cd>, Dune::PartitionSet<ps>). All other functions simply forward to this single function. Apart from that, you will of course have to overload intersections() and descendantElements() as well - those are entirely separate.

ADL lookup for grids in non-standard namespaces

The range generator functions described on this page are found by means of argument-dependent lookup (ADL). That way, users don't have to explicitly specify the namespace when using those functions.

Making ADL work does however require some care from grid implementors who are developing grids which are not placed in the namespace Dune. More precisely, the GridView and the Entity classes have to be in that namespace. If you are using the default facade classes, you don't have to worry about this fact (the facade classes are in the correct namespace), but if your implementation does not use those facades, you will have to import the functions on this page into the namespace of your GridView and / or Entity classes to make ADL work:

namespace MyAweSomeGrid {
 
  using Dune::entities;
  using Dune::elements;
  using Dune::facets;
  using Dune::edges;
  using Dune::vertices;
  using Dune::descendantElements;
  using Dune::intersections;
 
  ...
 
}

Of course, you can also reimplement all functions in your own namespace, but that's probably a bad idea...

Function Documentation

◆ descendantElements()

template<typename Entity >

IteratorRange<... > descendantElements	(	const Entity< cd, dim, GridImp, EntityImp > &	e,
		int	maxLevel
	)

This functions returns an object representing the range of descendat elements of the element (Entity with codimension 0) e. The main purpose of this function is to enable iteration over those descendants by means of a range-based for loop:

// iterate over all descendants of an entity
const auto& entity = ...; // get an entity from somewhere
for (const auto& e : descendantElements(entity,grid.maxLevel()))
{
  std::cout << e.geometry().center() << std::endl;
}

Note: This function only works for elements (entities with codimension 0). Attempting to call this function with an entity of higher codimension will result in a compile time error.

Parameters

e	the Entity whose descendants should be iterated over.
maxLevel	the maximum grid level for which to return descendants. Elements with `level > maxLevel` will be omitted from the range.

Returns: an unspecified object that is guaranteed to fulfil the interface of IteratorRange and that can be iterated over using a range-based for loop.

◆ edges() [1/2]

template<typename GV >

IteratorRange<... > edges ( const GV & gv )

This functions returns an object representing the range of edges contained in the GridView gv. The main purpose of this function is to enable iteration over those entities by means of a range-based for loop.

Example:

// iterate over all edges in the LeafGridView
auto gv = grid.leafGridView();
for (const auto& e : edges(gv))
{
  std::cout << e.geometry().center() << std::endl;
}

Remarks: This is the default version of the edges() function. It will always iterate over all elements in the GridView, regardless of their Dune::PartitionType. If you are interested in cells with specific PartitionType(s), use edges(const GV&,PartitionSet<partitions>) instead.

See also: edges(const GV&,PartitionSet<partitions>)

Parameters

gv	a GridView object that contains the edges.

Returns: an unspecified object that is guaranteed to fulfil the interface of IteratorRange and that can be iterated over using a range-based for loop.

◆ edges() [2/2]

template<typename GV , unsigned int partitions>

IteratorRange<... > edges	(	const GV &	gv,
		PartitionSet< partitions >	ps
	)

This functions returns an object representing the range of edges contained in the GridView gv which belong to the PartitionSet ps. The main purpose of this function is to enable iteration over those entities by means of a range-based for loop.

Example:

// iterate over all interior edges in the LeafGridView
auto gv = grid.leafGridView();
for (const auto& e : edges(gv,Dune::Partitions::interior))
{
  std::cout << e.geometry().center() << std::endl;
}

See also: edges(const GV&)

Parameters

gv	a GridView object that contains the edges.
ps	a PartitionSet object that is used to specify the set of Dune::PartitionType to which the edges must belong.

Returns: an unspecified object that is guaranteed to fulfil the interface of IteratorRange and that can be iterated over using a range-based for loop.

◆ elements() [1/2]

template<typename GV >

IteratorRange<... > elements ( const GV & gv )

This functions returns an object representing the range of elements or cells contained in the GridView gv. The main purpose of this function is to enable iteration over those entities by means of a range-based for loop.

Example:

// iterate over all cells in the LeafGridView
auto gv = grid.leafGridView();
for (const auto& e : elements(gv))
{
  std::cout << e.geometry().center() << std::endl;
}

Remarks: This is the default version of the elements() function. It will always iterate over all elements in the GridView, regardless of their Dune::PartitionType. If you are interested in cells with specific PartitionType(s), use elements(const GV&,PartitionSet<partitions>) instead.

See also: elements(const GV&,PartitionSet<partitions>)

Parameters

gv	a GridView object that contains the elements.

Returns: an unspecified object that is guaranteed to fulfil the interface of IteratorRange and that can be iterated over using a range-based for loop.

◆ elements() [2/2]

template<typename GV , unsigned int partitions>

IteratorRange<... > elements	(	const GV &	gv,
		PartitionSet< partitions >	ps
	)

This functions returns an object representing the range of elements or cells contained in the GridView gv which belong to the PartitionSet ps. The main purpose of this function is to enable iteration over those entities by means of a range-based for loop.

Example:

// iterate over all ghost cells in the LeafGridView
auto gv = grid.leafGridView();
for (const auto& e : elements(gv,Dune::Partitions::ghost))
{
  std::cout << e.geometry().center() << std::endl;
}

See also: elements(const GV&)

Parameters

gv	a GridView object that contains the elements.
ps	a PartitionSet object that is used to specify the set of Dune::PartitionType to which the elements must belong.

Returns: an unspecified object that is guaranteed to fulfil the interface of IteratorRange and that can be iterated over using a range-based for loop.

◆ entities() [1/4]

template<typename GV , int codim, unsigned int partitions>

IteratorRange<... > entities	(	const GV &gv	gv,
		Codim< codim >	cd,
		PartitionSet< partitions >	ps
	)

This functions returns an object representing the range of entities of codimension cd contained in the GridView gv which belong to the PartitionSet ps. The main purpose of this function is to enable iteration over those entities by means of a range-based for loop:

// iterate over all interior and border cells in the LeafGridView
auto gv = grid.leafGridView();
for (const auto& e : entities(gv,Dune::Codim<0>(),Dune::Partitions::interiorBorder))
{
  std::cout << e.geometry().center() << std::endl;
}

Remarks: This function allows you to write loops that are parameterized on the codimension of the entities. While this allows for extra flexibility (for e.g. some codimension-agnostic algorithms), it reduces the code readability. If you don't need this flexibility, consider using elements(), facets(), edges() or vertices() instead.; If you have to iterate over entities with a specific dimension, consider using entities(const GV&,Dim<dim>,PartitionSet<partitions>) instead to improve the readability of your code.

See also: entities(const GV&,Codim<codim>); entities(const GV&,Dim<dim>,PartitionSet<partitions>)

Parameters

gv	a GridView object that contains the entities.
cd	a Codim object that is used to specify the codimension of the entities by means of its template parameter.
ps	a PartitionSet object that is used to specify the set of Dune::PartitionType to which the entities must belong.

Returns: an unspecified object that is guaranteed to fulfil the interface of IteratorRange and that can be iterated over using a range-based for loop.

◆ entities() [2/4]

template<typename GV , int codim>

IteratorRange<... > entities	(	const GV &	gv,
		Codim< codim >	cd
	)

This functions returns an object representing the range of entities of codimension cd contained in the GridView gv. The main purpose of this function is to enable iteration over those entities by means of a range-based for loop:

// iterate over all cells in the LeafGridView
auto gv = grid.leafGridView();
for (const auto& e : entities(gv,Dune::Codim<0>()))
{
  std::cout << e.geometry().center() << std::endl;
}

Remarks: This function allows you to write loops that are parameterized on the codimension of the entities. While this allows for extra flexibility (for e.g. some codimension-agnostic algorithms), it reduces the code readability. If you don't need this flexibility, consider using elements(), facets(), edges() or vertices() instead.; This is the default version of the entities() function. It will always iterate over all entities in the GridView, regardless of their Dune::PartitionType. If you are interested in entities with specific PartitionType(s), use entities(const GV&,Codim<codim>,PartitionSet<partitions>) instead.; If you have to iterate over entities with a specific dimension, consider using entities(const GV&,Dim<dim>) instead to improve the readability of your code.

See also: entities(const GV&,Codim<codim>,PartitionSet<partitions>); entities(const GV&,Dim<dim>)

Parameters

gv	a GridView object that contains the entities.
cd	a Codim object that is used to specify the codimension of the entities by means of its template parameter.

Returns: an unspecified object that is guaranteed to fulfil the interface of IteratorRange and that can be iterated over using a range-based for loop.

◆ entities() [3/4]

template<typename GV , int dim>

IteratorRange<... > entities	(	const GV &	gv,
		Dim< dim >	d
	)

This functions returns an object representing the range of entities of dimension d contained in the GridView gv. The main purpose of this function is to enable iteration over those entities by means of a range-based for loop.

Example:

// iterate over all edges in the LeafGridView
auto gv = grid.leafGridView();
for (const auto& e : entities(gv,Dune::Dim<1>()))
{
  std::cout << e.geometry().center() << std::endl;
}

Remarks: This function allows you to write loops that are parameterized on the codimension of the entities. While this allows for extra flexibility (for e.g. some codimension-agnostic algorithms), it reduces the code readability. If you don't need this flexibility, consider using elements(), facets(), edges() or vertices() instead.; This is the default version of the entities() function. It will always iterate over all entities in the GridView, regardless of their Dune::PartitionType. If you are interested in entities with specific PartitionType(s), use entities(const GV&,Dim<dim>,PartitionSet<partitions>) instead.; If you have to iterate over entities with a specific codimension, consider using entities(const GV&,Codim<codim>) instead to improve the readability of your code.

See also: entities(const GV&,Dim<dim>,PartitionSet<partitions>); entities(const GV&,Codim<codim>)

Parameters

gv	a GridView object that contains the entities.
d	a Dim object that is used to specify the dimension of the entities by means of its template parameter.

Returns: an unspecified object that is guaranteed to fulfil the interface of IteratorRange and that can be iterated over using a range-based for loop.

◆ entities() [4/4]

template<typename GV , int dim, unsigned int partitions>

IteratorRange<... > entities	(	const GV &	gv,
		Dim< dim >	d,
		PartitionSet< partitions >	ps
	)

This functions returns an object representing the range of entities of dimension d contained in the GridView gv which belong to the PartitionSet ps. The main purpose of this function is to enable iteration over those entities by means of a range-based for loop:

// iterate over all interior and border edges in the LeafGridView
auto gv = grid.leafGridView();
for (const auto& e : entities(gv,Dune::Dim<1>(),Dune::Partitions::interiorBorder))
{
  std::cout << e.geometry().center() << std::endl;
}

Remarks: This function allows you to write loops that are parameterized on the dimension of the entities. While this allows for extra flexibility (for e.g. some codimension-agnostic algorithms), it reduces the code readability. If you don't need this flexibility, consider using elements(), facets(), edges() or vertices() instead.; If you have to iterate over entities with a specific codimension, consider using entities(const GV&,Codim<codim>,PartitionSet<partitions>) instead to improve the readability of your code.

See also: entities(const GV&,Dim<dim>); entities(const GV&,Codim<codim>,PartitionSet<partitions>)

Parameters

gv	a GridView object that contains the entities.
d	a Dim object that is used to specify the dimension of the entities by means of its template parameter.
ps	a PartitionSet object that is used to specify the set of Dune::PartitionType to which the entities must belong.

Returns: an unspecified object that is guaranteed to fulfil the interface of IteratorRange and that can be iterated over using a range-based for loop.

◆ facets() [1/2]

template<typename GV >

IteratorRange<... > facets ( const GV & gv )

This functions returns an object representing the range of facets contained in the GridView gv. The main purpose of this function is to enable iteration over those entities by means of a range-based for loop.

Example:

// iterate over all facets in the LeafGridView
auto gv = grid.leafGridView();
for (const auto& e : facets(gv))
{
  std::cout << e.geometry().center() << std::endl;
}

Remarks: This is the default version of the facets() function. It will always iterate over all elements in the GridView, regardless of their Dune::PartitionType. If you are interested in cells with specific PartitionType(s), use facets(const GV&,PartitionSet<partitions>) instead.

See also: facets(const GV&,PartitionSet<partitions>)

Parameters

gv	a GridView object that contains the facets.

Returns: an unspecified object that is guaranteed to fulfil the interface of IteratorRange and that can be iterated over using a range-based for loop.

◆ facets() [2/2]

template<typename GV , unsigned int partitions>

IteratorRange<... > facets	(	const GV &	gv,
		PartitionSet< partitions >	ps
	)

This functions returns an object representing the range of facets contained in the GridView gv which belong to the PartitionSet ps. The main purpose of this function is to enable iteration over those entities by means of a range-based for loop.

Example:

// iterate over all interior and border facets in the LeafGridView
auto gv = grid.leafGridView();
for (const auto& e : facets(gv,Dune::Partitions::interiorBorder))
{
  std::cout << e.geometry().center() << std::endl;
}

See also: facets(const GV&)

Parameters

gv	a GridView object that contains the facets.
ps	a PartitionSet object that is used to specify the set of Dune::PartitionType to which the facets must belong.

Returns: an unspecified object that is guaranteed to fulfil the interface of IteratorRange and that can be iterated over using a range-based for loop.

◆ intersections()

template<typename GV , typename Entity >

IteratorRange<... > intersections	(	const GV &	gv,
		const Entity< cd, dim, GridImp, EntityImp > &	e
	)

This functions returns an object representing the range of Intersections of the Entity e with respect to the GridView gv. The main purpose of this function is to enable iteration over those intersections by means of a range-based for loop:

// iterate over all intersections of an entity with respect to the LeafGridView
auto gv = grid.leafGridView();
const auto& entity = ...; // get an entity from somewhere
for (const auto& i : intersections(gv,entity))
{
  std::cout << i.geometry().center() << std::endl;
}

Parameters

gv	the GridView to use for determining interior intesections.
e	the Entity whose intersections should be iterated over.

Returns: an unspecified object that is guaranteed to fulfil the interface of IteratorRange and that can be iterated over using a range-based for loop.

◆ vertices() [1/2]

template<typename GV >

IteratorRange<... > vertices ( const GV & gv )

This functions returns an object representing the range of vertices contained in the GridView gv. The main purpose of this function is to enable iteration over those entities by means of a range-based for loop.

Example:

// iterate over all vertices in the LeafGridView
auto gv = grid.leafGridView();
for (const auto& e : vertices(gv))
{
  std::cout << e.geometry().center() << std::endl;
}

Remarks: This is the default version of the vertices() function. It will always iterate over all elements in the GridView, regardless of their Dune::PartitionType. If you are interested in cells with specific PartitionType(s), use vertices(const GV&,PartitionSet<partitions>) instead.

See also: vertices(const GV&,PartitionSet<partitions>)

Parameters

gv	a GridView object that contains the vertices.

Returns: an unspecified object that is guaranteed to fulfil the interface of IteratorRange and that can be iterated over using a range-based for loop.

◆ vertices() [2/2]

template<typename GV , unsigned int partitions>

IteratorRange<... > vertices	(	const GV &	gv,
		PartitionSet< partitions >	ps
	)

This functions returns an object representing the range of vertices contained in the GridView gv which belong to the PartitionSet ps. The main purpose of this function is to enable iteration over those entities by means of a range-based for loop.

Example:

// iterate over all interior vertices in the LeafGridView
auto gv = grid.leafGridView();
for (const auto& e : vertices(gv,Dune::Partitions::interior))
{
  std::cout << e.geometry().center() << std::endl;
}

See also: vertices(const GV&)

Parameters

gv	a GridView object that contains the vertices.
ps	a PartitionSet object that is used to specify the set of Dune::PartitionType to which the vertices must belong.

Returns: an unspecified object that is guaranteed to fulfil the interface of IteratorRange and that can be iterated over using a range-based for loop.

DUNE Distributed and Unified Numerics Environment

Dune Core Modules (2.5.0)

Common entity ranges

Intersection Range

Hierarchic Entity range

Entity ranges with (co)dimension template argument

Common entity ranges for non-standard parallel partitions

Generic entity ranges for non-standard parallel partitions

Detailed Description

Range-based for loop

Entities

Intersections

Information for grid implementors

Custom range implementations

ADL lookup for grids in non-standard namespaces

Function Documentation

◆ descendantElements()

◆ edges() [1/2]

◆ edges() [2/2]

◆ elements() [1/2]

◆ elements() [2/2]

◆ entities() [1/4]

◆ entities() [2/4]

◆ entities() [3/4]

◆ entities() [4/4]

◆ facets() [1/2]

◆ facets() [2/2]

◆ intersections()

◆ vertices() [1/2]

◆ vertices() [2/2]