]> https://gitweb.dealii.org/ - dealii.git/commitdiff
Add the Assert discussion back in to step-5.
authorDavid Wells <wellsd2@rpi.edu>
Sun, 17 Jul 2016 19:19:39 +0000 (15:19 -0400)
committerDavid Wells <wellsd2@rpi.edu>
Fri, 29 Jul 2016 00:14:31 +0000 (20:14 -0400)
Additionally, the library now has 9375 Asserts and AssertThrows, so
increase the number of exceptions from 4200.

examples/step-5/doc/tooltip
examples/step-5/step-5.cc

index 51b43ab8ecd2f4a9f2e8ea9622aff3b124ff734f..edd376e8c3f94097ad2f1fb53e99ce9294f9787e 100644 (file)
@@ -1 +1 @@
-Reading a grid from disk. Computations on successively refined grids. Variable coefficients.
+Reading a grid from disk. Computations on successively refined grids. Variable coefficients. Assertions.
index 75aba1a041f85f9bef6ad8afd90e933863c68b92..fabe3c8f447caadbcf1b42705ee8dc3b6ee13c95 100644 (file)
@@ -404,7 +404,43 @@ void Step5<dim>::run ()
   // two-dimensional triangulation, while this function is a template for
   // arbitrary dimension. Since this is only a demonstration program, we will
   // not use different input files for the different dimensions, but rather
-  // kill the whole program if we are not in 2D:
+  // quickly kill the whole program if we are not in 2D. Of course, since the
+  // main function below assumes that we are working in two dimensions we
+  // could skip this check, in this version of the program, without any ill
+  // effects.
+  //
+  // It turns out that more than 90 per cent of programming errors are invalid
+  // function parameters such as invalid array sizes, etc, so we use
+  // assertions heavily throughout deal.II to catch such mistakes. For this,
+  // the <code>Assert</code> macro is a good choice, since it makes sure that
+  // the condition which is given as first argument is valid, and if not
+  // throws an exception (its second argument) which will usually terminate
+  // the program giving information where the error occurred and what the
+  // reason was. This generally reduces the time to find programming errors
+  // dramatically and we have found assertions an invaluable means to program
+  // fast.
+  //
+  // On the other hand, all these checks (there are over 9000 of them in the
+  // library at present) should not slow down the program too much if you want
+  // to do large computations. To this end, the <code>Assert</code> macro is
+  // only used in debug mode and expands to nothing if in optimized
+  // mode. Therefore, while you test your program on small problems and debug
+  // it, the assertions will tell you where the problems are. Once your
+  // program is stable, you can switch off debugging and the program will run
+  // your real computations without the assertions and at maximum speed. More
+  // precisely: turning off all the checks in the library (which prevent you
+  // from calling functions with wrong arguments, walking off of arrays, etc.)
+  // by compiling your program in optimized mode usually makes things run
+  // about four times faster. Even though optimized programs are more
+  // performant, we still recommend developing in debug mode since it allows
+  // the library to find lots of common programming errors automatically. For
+  // those who want to try: The way to switch from debug mode to optimized
+  // mode is to recompile your program with the command <code>make
+  // release</code>. The output of the <code>make</code> program should now
+  // indicate to you that the program is now compiled in optimized mode, and
+  // it will later also be linked to libraries that have been compiled for
+  // optimized mode. In order to switch back to debug mode, simply recompile
+  // with the command <code>make debug</code>.
   Assert (dim==2, ExcInternalError());
   // ExcInternalError is a globally defined exception, which may be thrown
   // whenever something is terribly wrong. Usually, one would like to use more

In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.

Douglas Adams


Typeset in Trocchi and Trocchi Bold Sans Serif.