dune-grid 2.9.0
|
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... | |
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.
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.
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:
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
:
The grid interface allows to iterate over sub-entities of a given codim-0-entity, sub-entities being entities contained in the given entitiy 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).
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.
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...
|
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:
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. |
|
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:
gv | a GridView object that contains the edges. |
|
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:
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. |
|
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:
gv | a GridView object that contains the elements. |
|
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:
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. |
|
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:
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. |
|
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:
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. |
|
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:
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. |
|
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:
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. |
|
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:
gv | a GridView object that contains the facets. |
|
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:
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. |
|
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:
gv | the GridView to use for determining interior intesections. |
e | the Entity whose intersections should be iterated over. |
|
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:
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. |
size()
member function.
|
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:
gv | a GridView object that contains the vertices. |
|
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:
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. |