From d115ea3123346b9e1afb3604ac70a1fe8d1f2275 Mon Sep 17 00:00:00 2001 From: David Wells Date: Sun, 17 Jul 2016 15:19:39 -0400 Subject: [PATCH] Add the Assert discussion back in to step-5. Additionally, the library now has 9375 Asserts and AssertThrows, so increase the number of exceptions from 4200. --- examples/step-5/doc/tooltip | 2 +- examples/step-5/step-5.cc | 38 ++++++++++++++++++++++++++++++++++++- 2 files changed, 38 insertions(+), 2 deletions(-) diff --git a/examples/step-5/doc/tooltip b/examples/step-5/doc/tooltip index 51b43ab8ec..edd376e8c3 100644 --- a/examples/step-5/doc/tooltip +++ b/examples/step-5/doc/tooltip @@ -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. diff --git a/examples/step-5/step-5.cc b/examples/step-5/step-5.cc index 75aba1a041..fabe3c8f44 100644 --- a/examples/step-5/step-5.cc +++ b/examples/step-5/step-5.cc @@ -404,7 +404,43 @@ void Step5::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 Assert 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 Assert 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 make + // release. The output of the make 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 make debug. 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 -- 2.39.5