From: Wolfgang Bangerth Date: Sun, 16 Jun 2013 14:09:39 +0000 (+0000) Subject: Document global_dof_index. X-Git-Tag: v8.0.0~290 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=fd91341dbd158a9c5cebf046d98fe708b7befbe4;p=dealii.git Document global_dof_index. git-svn-id: https://svn.dealii.org/trunk@29819 0785d39b-7218-0410-832d-ea1e28bc413d --- diff --git a/deal.II/examples/step-3/doc/intro.dox b/deal.II/examples/step-3/doc/intro.dox index ad3f4abe64..6af4c4db2a 100644 --- a/deal.II/examples/step-3/doc/intro.dox +++ b/deal.II/examples/step-3/doc/intro.dox @@ -315,4 +315,71 @@ separation of functionality — again in many of the following tutorial programs. +

A note on types

+deal.II defines a number of integral %types via typedefs in +namespace types. In particular, in this program you will see +types::global_dof_index in a couple of places: an integer type that is used to +denote the global index of a degree of freedom, i.e., the index of a +particular degree of freedom within the DoFHandler object that is defined on +top of a triangulation (as opposed to the index of a particular degree of +freedom within a particular cell). For the current program +(as well as almost all of the tutorial programs), you will have a few thousand +to maybe a few million unknowns globally (and, for $Q_1$ elements, you will +have 4 locally on each cell in 2d and 8 in 3d). Consequently, a data +type that allows to store sufficiently large numbers for global DoF indices is +unsigned int given that it allows to store numbers between 0 and +slightly more than 4 billion (on most systems, where integers are 32-bit). In +fact, this is what types::global_dof_index is. + +So, why not just use unsigned int right away? deal.II used to do +this until version 7.3. However, deal.II supports very large computations (via +the framework discussed in step-40) that may have more than 4 billion unknowns +when spread across a few thousand processors. Consequently, there are +situations where unsigned int is not sufficiently large and we +need a 64-bit unsigned integral type. To make this possible, we introduced +types::global_dof_index which by default is defined as simply unsigned +int whereas it is possible to define it as unsigned long long +int if necessary, by passing a particular flag during configuration +(see the ReadMe file). + +This covers the technical aspect. But there is also a documentation purpose: +everywhere in the library and codes that are built on it, if you see a place +using the data type types::global_dof_index, you immediately know that the +quantity that is being referenced is, in fact, a global dof index. No such +meaning would be apparent if we had just used unsigned int (which +may also be a local index, a boundary indicator, a material id, +etc.). Immediately knowing what a variable refers to also helps avoid errors: +it's quite clear that there must be a bug if you see an object of type +types::global_dof_index being assigned to variable of type +types::subdomain_id, even though they are both represented by unsigned +integers and the compiler will, consequently, not complain. + +In more practical terms what the presence of this type means is that during +assembly, we create a $4\times 4$ matrix (in 2d, using a $Q_1$ element) of the +contributions of the cell we are currently sitting on, and then we need to add +the elements of this matrix to the appropriate elements of the global (system) +matrix. For this, we need to get at the global indices of the degrees of +freedom that are local to the current cell, for which we will always use the +following piece of the code: +@code + cell->get_dof_indices (local_dof_indices); +@endcode +where local_dof_indices is declared as +@code + std::vector local_dof_indices (fe.dofs_per_cell); +@endcode +The name of this variable might be a bit of a misnomer -- it stands for "the +global indices of those degrees of freedom locally defined on the current +cell" -- but variables that hold this information are universally named this +way throughout the library. + +@note types::global_dof_index is not the only type defined in this +namespace. Rather, there is a whole family, including types::subdomain_id, +types::boundary_id, and types::material_id. All of these are +typedefs for integer data types but, as explained above, they are +used throughout the library so that (i) the intent of a variable becomes more +easily discerned, and (ii) so that it becomes possible to change the actual +type to a large one if necessary without having to go through the entire +library and figure out whether a particular use of unsigned int +corresponds to, say, a material indicator.