From: wolf Date: Thu, 23 Dec 1999 14:25:42 +0000 (+0000) Subject: Add much text. X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=c1cc8d134363d331bebee7d245050d610d3345c3;p=dealii-svn.git Add much text. git-svn-id: https://svn.dealii.org/trunk@2124 0785d39b-7218-0410-832d-ea1e28bc413d --- diff --git a/deal.II/doc/tutorial/chapter-2.step-by-step/step-4.intro b/deal.II/doc/tutorial/chapter-2.step-by-step/step-4.intro index 1518606e43..35c826cb31 100644 --- a/deal.II/doc/tutorial/chapter-2.step-by-step/step-4.intro +++ b/deal.II/doc/tutorial/chapter-2.step-by-step/step-4.intro @@ -1,3 +1,127 @@

Introduction

+deal.II has a unique feature which we call +``dimension independent programming''. You may have noticed in the +previous examples that many classes had a number in angle brackets +suffixed to them. This is to indicate that for example the +triangulation in two and three space dimensions are different, but +related data types. We could as well have called them +Triangulation2d and Triangulation3d instead +of Triangulation<2> and +Triangulation<3> to name the two classes, but this +has an important drawback: assume you have a function which does +exactly the same functionality, but on 2d or 3d triangulations, +depending on which dimension we would like to solve the equation in +presently (if you don't believe that it is the common case that a +function does something that is the same in all dimensions, just take +a look at the code below - there are almost no distinctions between 2d +and 3d!). We would have to write the same function twice, once +working on Triangulation2d and once working with a +Triangulation3d. This is an unnecessary obstacle in +programming and leads to a nuisance to keep the two function in synch +(at best) or difficult to find errors if the two versions get out of +synch (at worst; this would probably the more common case). + +

+ +Such obstacles can be circumvented by using some template magic as +provided by the C++ language: templatized classes and functions are +not really classes or functions but only a pattern depending on an +as-yet undefined data type parameter or on a numerical value which is +also unknown at the point of definition. However, the compiler can +build proper classes or functions from these templates if you provide +it with the information that is needed for that. Of course, parts of +the template can depend on the template parameters, and they will be +resolved at the time of compilation for a specific template +parameter. For example, consider the following piece of code: +


+  template <int dim>
+  void make_grid (Triangulation<dim> &triangulation)
+  {
+    GridGenerator::hyper_cube (triangulation, -1, 1);
+  };
+
+ +At the point where the compiler sees this function, it does not know +anything about the value of ``dim'', by now there is a whole zoo of +functions make_grid, one for every possible valueof ``dim''. But since +the compiler can't know which might be used, it can not compile the +function. + +

+ +However, if later down a function would use the following sequence, +


+  Triangulation<2> triangulation;
+  make_grid (triangulation);
+
+the compiler will deduce that the function make_grid for dim==2 was +requested and will compile that function with dim replaced by 2 +everywhere, i.e. it will compiler the function as if it were defined +as +

+  void make_grid (Triangulation<2> &triangulation)
+  {
+    GridGenerator::hyper_cube (triangulation, -1, 1);
+  };
+
+ +

+ +However, it is worth to note that the function +GridGenerator::hyper_cube depends on the dimension as +well, so in this case, the compiler will call the function +GridGenerator::hyper_cube<2> while if dim were 3, +it would call GridGenerator::hyper_cube<3> which +might be (and actually is) a totally unrelated function. + + +

+ +The same can be made with member variables. Consider the following +function, which might in turn call the above one: +


+  template <int dim>
+  void make_grid_and_dofs (Triangulation<dim> &triangulation)
+  {
+    make_grid (triangulation);
+
+    DoFHandler<dim> dof_handler;
+    ...
+  };
+
+ +This function has a member variable of type +DoFHandler<dim> the size of which may (and does) +depend on the dimension we are working in. Again, the compiler can't +compile this function until it knows for which dimension and therefore +how many space shall be reserved for the member variable. If you call +this function for a specific dimension as above, the compiler will +take the template, replace all occurences of dim by the dimension for +which it was called, and compile it. If you call the function several +times for different dimensions, it will compile it several times, each +time calling the right ``make_grid'' function and reserving the right +amount of memory for the member variable. + +

+ +The deal.II library is build around this concept +and that allows you to program in way that will not need to +distinguish between the space dimensions. It should be noted that in +only a very few places is it necessary to actually compare the +dimension using ``if''s or ``switch''es. However, since the compiler +has to compile each function for each dimension separately, even there +it knows the value of ``dim'' at the time of compilation and will +therefore be able to optimize the ``if'' statement along with the +unused branch. + +

+ +In this example program, we will show how to program dimension +independently (which in fact is even simpler than if you had to take +care about the dimension) and we will extend the Laplace problem of +the last example to a program that runs in two and three space +dimensions at the same time. Other extensions are the use of a +non-constant right hand side function and of non-zero boundary values. +