DUNE PDELab (git)
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, 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... | |
template<typename E , int codim> | |
IteratorRange<... > | subEntities (const E &e, Codim< codim > c) |
Iterates over all sub-entities of an entity given the codimension of the sub-entities. 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:
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
.
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 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:
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:
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
:
Sub-entities
The grid interface allows to iterate over sub-entities of a given codim-0-entity, sub-entities being entities contained in the given entity with a codimension equal (returns the entity itself) or larger than the given entity.
As an example, the following code prints the index of all vertices of an element e
Note that the number of for example codim-1 entities (facets) of an element can be obtained with
which is equivalent to
Iteration over sub-entities is only possible for codim-0-entities (elements).
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:
Of course, you can also reimplement all functions in your own namespace, but that's probably a bad idea...
Function Documentation
◆ descendantElements()
|
related |
Iterates over all descendant elements of the given element up to a maximum level.
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:
- 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]
|
related |
Iterates over all edges (entities with dimension 1) of a GridView.
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:
- 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.
- 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.
- Examples
- recipe-iterate-over-grid.cc.
◆ edges() [2/2]
|
related |
Iterates over all edges (entities with dimension 1) of a GridView that belong to the given PartitionSet.
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:
- 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]
|
related |
Iterates over all elements / cells (entities with codimension 0) of a GridView.
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:
- 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.
- 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.
- Examples
- recipe-integration.cc, and recipe-iterate-over-grid.cc.
Referenced by checkElementDataMapper(), checkMixedDataMapper(), and checkVertexDataMapper().
◆ elements() [2/2]
|
related |
Iterates over all elements / cells (entities with codimension 0) of a GridView that belong to the given PartitionSet.
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:
- 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 fulfill the interface of IteratorRange and that can be iterated over using a range-based for loop.
◆ entities() [1/4]
|
related |
Iterates over all entities of a GridView with the given codimension.
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:
- 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.
- 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.
- Examples
- recipe-iterate-over-grid.cc.
◆ entities() [2/4]
|
related |
Iterates over all entities of a GridView with the given codimension that belong to the given PartitionSet.
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:
- 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.
- 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() [3/4]
|
related |
Iterates over all entities of a GridView with the given dimension.
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:
- 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.
- 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]
|
related |
Iterates over all entities of a GridView with the given dimension that belong to the given PartitionSet.
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:
- 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.
- 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]
|
related |
Iterates over all facets (entities with codimension 1) of a GridView.
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:
- 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.
- 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.
- Examples
- recipe-iterate-over-grid.cc.
◆ facets() [2/2]
|
related |
Iterates over all facets (entities with codimension 1) of a GridView that belong to the given PartitionSet.
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:
- 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()
|
related |
Iterates over all Intersections of an Entity with respect to the given GridView.
This functions returns an object representing the range of Intersection
s 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:
- 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.
- Examples
- recipe-integration.cc.
◆ subEntities()
|
related |
Iterates over all sub-entities of an entity given the codimension of the sub-entities.
This functions returns an object representing the range of sub-entities of codimension c contained in the given entity. The main purpose of this function is to enable iteration over sub-entities by means of a range-based for loop:
- Note
- This functionality is only available for codim-0-entities (elements)
- Parameters
-
e an Entity object that contains the sub-entities. c a Codim object that is used to specify the codimension of the sub-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 and that provides a
size()
member function.
◆ vertices() [1/2]
|
related |
Iterates over all vertices (entities with dimension 0) of a GridView.
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:
- 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.
- 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.
- Examples
- recipe-iterate-over-grid.cc.
◆ vertices() [2/2]
|
related |
Iterates over all vertices (entities with dimension 0) of a GridView that belong to the given PartitionSet.
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:
- 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.