From: wolf Date: Mon, 3 Apr 2000 12:40:15 +0000 (+0000) Subject: Index the functions offered by tria accessors. X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=b6b51bf4875a53335f77833e98a35333c59c5a56;p=dealii-svn.git Index the functions offered by tria accessors. git-svn-id: https://svn.dealii.org/trunk@2659 0785d39b-7218-0410-832d-ea1e28bc413d --- diff --git a/deal.II/doc/reports/class-hierarchies/index.html b/deal.II/doc/reports/class-hierarchies/index.html index dddadef0e2..079dae196b 100644 --- a/deal.II/doc/reports/class-hierarchies/index.html +++ b/deal.II/doc/reports/class-hierarchies/index.html @@ -18,10 +18,11 @@ accessor classes

- Wolfgang Bangerth, 1998, 1999 + Wolfgang Bangerth, 1998, 1999, 2000

+

The class hierarchy of the accessor classes used to retrieve and store data in the triangulation and degree of freedom handler objects is one of the more complicated parts of the library. It makes heavy use of @@ -30,6 +31,7 @@ explicit specialization of classes and member functions. Therefore, it is not so easy to see the connections and inheritance relations within this part of the class tree; this document tries to shed a bit of light onto this. +

@@ -37,6 +39,7 @@ of light onto this. What iterators and accessors are +

When using adative finite elements, the data structures often are extremely complex, requiring multiply indirected access and complex relationships between the different places where data is stored. The @@ -47,9 +50,9 @@ consumption (when you have to store many small data pieces and because you have to store a lot of pointers to other objects) or higher coding requirements (when you want to follow all those pointers to the object you desire). +

-

- +

Therefore, we took over a concept which was already used in the C++ standard template library, namely iterators and accessors. An accessor is an object that looks like if it had all the information stored but @@ -66,9 +69,9 @@ programs as well as those parts of the library which only act through accessors; and third by reducing the coding errors because of reduced complexity, since the chains of indirect access are replaces by simple commands. +

-

- +

Iterators are a related concept: while accessors act as if they were structures with data contained in them, iterators act as if they were pointers pointing to accessors. You can dereference them using the @@ -81,9 +84,9 @@ as if it were a contiguous array. The iterators in this library go even a step further: they do not point to different objects but rather tell the associated accessor object which data to look at next. +

-

- +

Additionally, there are different versions of the iterators which behave differently when being incremented or decremented: while raw iterators let the associated accessor point to any of the @@ -98,9 +101,9 @@ the library. Normal iterators are almost like raw iterators, but whenever you call the ++ or -- operator, the look at what they are pointing at and skip all unused elements by increasing or decreasing the pointer as often as necessary to reach the next used object. +

-

- +

Finally, there are active iterators, which are the most important ones. They are like normal iterators but only point to active cells or lines. By active we mean that they have no children; @@ -108,6 +111,7 @@ in the context in which this library is used, this is equivalent to the fact that we do computations on these cells, lines or whatever. Active iterators are normal iterators which skip over all non-active cells, lines, etc when being incremented or decremented. +

@@ -115,6 +119,7 @@ non-active cells, lines, etc when being incremented or decremented. The triangulation accessor hierarchy +

The triangulation accessors are used to retrieve and store data in the triangulation. There exist accessors for lines in one and higher dimensions, accessors for quads in two and higher dimensions, and so @@ -130,47 +135,52 @@ on. The general naming scheme is as follows: properties that a cell has. It is therefore derived from TriaObjectAccessor<spacedimdim,spacedim>. +

- - +

Their inheritance trees in the different space dimensions therefore look like this: +


-

+


-

+


-

+


+

Some of the data is only useful if an object is a cell. For example, neighborship is only accessible for cells, while faces (e.g. lines in 2D) can't access their neighbors (neither the adjacent cells, nor the other faces it touches). Therefore, the CellAccessor classes are derived from whatever object a cell is in the respective dimension, i.e. from lines in 1D, from quads in 2D, and so on. +

+

Typedefs of the Triangulation class to iterators and accessors

+

The Triangulation<1> class declares the following data types which involve accessors:

@@ -184,9 +194,9 @@ types which involve accessors:
 
Since lines are cells in one space dimension, all line iterators are cell iterators as well. +

-

- +

In two space dimensions, the following types are declared by the Triangulation<2> class:

@@ -206,15 +216,13 @@ In two space dimensions, the following types are declared by the
     typedef        line_iterator        face_iterator;
     typedef active_line_iterator active_face_iterator;    
 
- Since in this space dimension, quads are cells and lines are the faces of cells, the appropriate face and cell iterators are declared in terms of the underlying accessor types. +

- -

- +

In three space dimensions, the following types are declared by the Triangulation<3> class:

@@ -238,10 +246,433 @@ In three space dimensions, the following types are declared by the
     typedef        quad_iterator        face_iterator;
     typedef active_quad_iterator active_face_iterator;    
 
- Since in this space dimension, hexes are cells and quads are the faces of cells, the appropriate face and cell iterators are declared in terms of the underlying accessor types. +

+ + + +

Functions offered by triangulation accessors

+ +

+We briefly state a short list of the functions offered by the +triangulation accessors. For a more complete discussion of these +functions, please refer to the online +API +documentation of the `grid' classes. These functions can be +accessed by iterator->function() if iterator +is a cell-, face-, hex-, quad-, or line-iterator. Some functions are +not available for all iterator types, which is noted for the +individual entries. +

+ +
+
+ level () +
+ +
+ Return the hierarchical refinement level on + which this object lives. +
+ + +
+ index () +
+ +
+ Return the index within the hierarchical refinement level on + which this object lives. +
+ + +
+ get_triangulation () +
+ +
+ Return a reference to the triangulation to which this object belongs. +
+ + +
+ vertex_index (vertex_number) +
+ +
+ Return the global index of one of the vertices of this object. +
+ + +
+ vertex (vertex_number) +
+ +
+ Return the position of the respective vertex in space. +
+ + +
+ used () +
+ +
+ Return whether the object is used. The return value is + true for all iterators that are either normal iterators + or active iterators, only raw iterators can return + false. Since raw iterators are only used in the + interiors of the library, you will not usually need this function. +
+ + +
+ set_used () / clear_used () +
+ +
+ Set or clear the flag that describes whether the object is used by + the triangulation. Only for internal use. +
+ + +
+ user_flag_set () +
+ +
+ Return whether the user flag is set. +
+ + +
+ set_user_flag () / clear_user_flag () +
+ +
+ Set or clear the flag that might be used by a user to indicate that + something should happen with this object. +
+ + +
+ recursively_set_user_flag () / recursively_clear_user_flag () +
+ +
+ Set or clear the user flag for this cell and all its descendants. +
+ + +
+ user_pointer () +
+ +
+ Query the pointer belonging to this object which may be used by + the user to store additional information with this object. +
+ + +
+ set_user_pointer () / clear_user_pointer () +
+ +
+ Set or clear a pointer belonging to this object which may be used by + the user to store additional information with this object. +
+ + +
+ child (child_number) +
+ +
+ Return an iterator to one of the children of this object. +
+ + +
+ child_index (child_number) +
+ +
+ Return the index of the child within the next finer level of the + triangulation. +
+ + +
+ set_children (index), clear_children () +
+ +
+ Only for internal use. +
+ + +
+ has_children () +
+ +
+ Return whether an object has children, i.e. whether it is further + refined. If it has children, then it is not active. +
+ + +
+ max_refinement_depth () +
+ +
+ Return how often this cell or one of its children is refined. +
+ + +
+ boundary_indicator +
+ +
+ Return the number of the boundary at which this object lies, if the + object has a dimension less than the space dimension. +
+ + +
+ set_boundary_indicator (boundary_id) +
+ +
+ Set the number of the boundary to which this object belongs. +
+ + +
+ at_boundary () +
+ +
+ Return whether this object is at the boundary. (Only available if + the dimension of the object is less than the space dimension.) +
+ + +
+ diameter () +
+ +
+ Return the diameter of the object. +
+ + +
+ center () +
+ +
+ Return the coordinates of the center of the object. +
+ + +
+ barycenter () +
+ +
+ Return the coordinates of the barycenter of the object. +
+ + +
+ measure () +
+ +
+ Return the length, area, or volume of an object, depending on the + dimension of the object. +
+ + +
+ number_of_children () +
+ +
+ Accumulated number of children and their children. +
+ + +
+ line (line_number) +
+ +
+ Return an iterator to one of the bounding lines of this object. (Only + for iterators to quadrilaterals and hexahedra.) +
+ + +
+ line_index (line_number) +
+ +
+ Return the index of one of the bounding lines of this object. The + level index is the same as that of the present object. (Only + for iterators to quadrilaterals and hexahedra.) +
+ + +
+ quad (quad_number) +
+ +
+ Return an iterator to one of the bounding quadrilaterals of this + object. (Only for iterators to hexahedra.) +
+ + +
+ line_index (line_number) +
+ +
+ Return the index of one of the bounding quadrilaterals of this + object. The level index is the same as that of the present + object. (Only for iterators to hexahedra.) +
+ + +
+ neighbor (neighbor_number) +
+ +
+ Return iterator to one of the neighbors. (Only for cell iterators.) +
+ + +
+ neighbor_index (neighbor_number) / neighbor_level (neighbor_number) +
+ +
+ Return number and level of one of the neighbors. (Only for cell + iterators.) +
+ + +
+ set_neighbor () +
+ +
+ Set a neighbor. Only for internal use. (Only for cell iterators.) +
+ + +
+ neighbor_of_neighbor (neighbor_number) +
+ +
+ Return the how-manyth neighbor the present cell is of the neighbor + specified by the argument. (Only for cell iterators.) +
+ + +
+ at_boundary (face_number) +
+ +
+ Return whether this cell's given face is at the boundary. (Only for + cell iterators.) +
+ + +
+ refine_flag_set () +
+ +
+ Return whether the refinement flag is set or not for the present + cell. (Only for cell iterators.) +
+ + +
+ set_refine_flag () / clear_refine_flag () +
+ +
+ Set/clear the flag indicating refinement. (Only for cell iterators.) +
+ + +
+ coarsen_flag_set () +
+ +
+ Query whether the flag indicating coarsening is set for this + object. (Only for cell iterators.) +
+ + +
+ set_coarsen_flag () / claer_coarsen_flag () +
+ +
+ Set/clear the flag indicating coarsening. (Only for cell iterators.) +
+ + +
+ face (face_number) +
+ +
+ Return an iterator to one of the faces of this cell, if dimension is + greater than one. (Only for cell iterators.) +
+ + +
+ material_id () +
+ +
+ Return the material number of this cell. (Only for cell iterators.) +
+ + +
+ set_material_id (id) +
+ +
+ Set the material number of this cell. (Only for cell iterators.) +
+ + +
+ active () +
+ +
+ Return whether this cell is active, i.e. has no children. (Only for + cell iterators.) +
+
@@ -250,7 +681,7 @@ terms of the underlying accessor types. The degree of freedom accessor hierarchy - +

The DoFAccessor classes provide access to the degree of freedom information associated with cells, lines, etc. The inheritance relationship is much the same as for the triangulation accessor @@ -261,7 +692,7 @@ classes, as can be seen from the following pictures.

-

+


@@ -269,7 +700,7 @@ classes, as can be seen from the following pictures.
-

+


@@ -277,19 +708,20 @@ classes, as can be seen from the following pictures.
-

+


+

The main difference to the triangulation accessor hierarchy is that we want the DoF accessors to provide the information about the degrees of freedom, but for convenience also that of the triangulation. This way, we can get all the information from one object rather than needing two which work in parallel, and the class hierarchy shown above does exactly this. +

-

- +

For the named reason, it is necessary to derive the DoFObjectAccessor<1,dim> from the TriaObjectAccessor<1,dim> class of the @@ -305,20 +737,20 @@ the DoFObjectAccessor<2,dim> class. Note that this way, CellAccessor is always a base class to DoFCellAccessor and the inheritance lattice is dimension dependant; the exact way of achieving this is complicated but not of interest here. +

Typedefs of the DoFHandler class to iterators and accessors

- +

The typedefs done by the DoFHandler class are much alike those done by the Triangulation class. They could be summarized as follows: +

-

- +

For one space dimension: -

     typedef TriaRawIterator   <1,DoFCellAccessor<1> >    raw_line_iterator;
     typedef TriaIterator      <1,DoFCellAccessor<1> >        line_iterator;
@@ -330,11 +762,10 @@ For one space dimension:
 
Since lines are cells in one space dimension, all line iterators are cell iterators as well. +

-

- +

For two space dimensions: -

     typedef TriaRawIterator   <2,DoFObjectAccessor<1, 2> >    raw_line_iterator;
     typedef TriaIterator      <2,DoFObjectAccessor<1, 2> >        line_iterator;
@@ -352,12 +783,10 @@ For two space dimensions:
     typedef        line_iterator        face_iterator;
     typedef active_line_iterator active_face_iterator;    
 
+

- -

- +

For three space dimensions: -

     typedef TriaRawIterator   <3,DoFObjectAccessor<1, 3> >    raw_line_iterator;
     typedef TriaIterator      <3,DoFObjectAccessor<1, 3> >        line_iterator;
@@ -379,14 +808,14 @@ For three space dimensions:
     typedef        quad_iterator        face_iterator;
     typedef active_quad_iterator active_face_iterator;    
 
+

- -


+
-Wolfgang Bangerth, 1998, 1999 +Wolfgang Bangerth, 1998, 1999, 2000
-

 

+