Added old wiki
authorLuca Heltai <luca.heltai@sissa.it>
Fri, 12 Dec 2014 17:43:22 +0000 (18:43 +0100)
committerLuca Heltai <luca.heltai@sissa.it>
Fri, 12 Dec 2014 17:43:22 +0000 (18:43 +0100)
15 files changed:
-Develop.md [new file with mode: 0644]
Build-Tests.md [new file with mode: 0644]
DoF-Handler.md [new file with mode: 0644]
Eclipse.md [new file with mode: 0644]
Frequently-Asked-Questions.md [new file with mode: 0644]
Function-Plotting-Tool.md [new file with mode: 0644]
Gallery.md [new file with mode: 0644]
Interfacing-With-Matlab.md [new file with mode: 0644]
Literature.md [new file with mode: 0644]
MacOSX.md [new file with mode: 0644]
Mesh-Input-And-Output.md [new file with mode: 0644]
Windows.md [new file with mode: 0644]
dbinit.md [new file with mode: 0644]
ealii-Users-Worldwide.md [new file with mode: 0644]
macs.md [new file with mode: 0644]

diff --git a/-Develop.md b/-Develop.md
new file mode 100644 (file)
index 0000000..dec90ce
--- /dev/null
@@ -0,0 +1,433 @@
+# An overview of using the KDevelop IDE and setting up deal.II in it
+
+<!-- No auto-Table of Contents support! -->
+
+## Overview
+
+[KDevelop](http://www.KDevelop.org) is a modern integrated development
+environment (IDE) for C++ (and other languages) that is part of the
+[KDE desktop environment](http://www.kde.org) project. As such it runs on Linux
+(even if you run one of the other desktops, such as GNOME) but it is
+also available for most other variants of Unix as well as on Windows.
+
+KDevelop offers all modern amenities of IDEs. For a large project like deal.II
+and applications built on it, the most important feature is that KDevelop
+**understands C++**: it parses the entire source base and remembers which classes
+have which member functions. For example, when you then type
+<code>
+  Vector<double> v(10);
+  double n = v.l2
+</code>
+it will have remembered that the `v` is a variable of type
+`Vector` and offer you to complete `l2` as
+`l2_norm` since this is the only member function of the
+`Vector` class that starts like this. Instead of continuing to type
+you just hit enter to get the full word; this saves typing, avoids typos, and
+doesn't require you to remember all those ridiculously long names in deal.II. This, by the way, would also have worked if the vector `v` had been declared in an entirely different file, maybe as a member variable of the surrounding class in some header file.
+
+As a second example, assume you have code like this:
+<code>
+double foo ()
+{
+  double var = my_func();
+  return var ** var;
+}
+
+double bar ()
+{
+  double var = my_func();
+  return var ** var * var;
+}
+</code>
+If you hover the mouse over the symbol `var` in function `bar` you get the option to see all uses of this symbol. Clicking on it will only show you the uses of this variable in function `bar` because KDevelop understands that the variable `var` in function `foo` has nothing to do with it. Similarly, right clicking on the variable name allows you to rename the variable; doing so will only touch the variable in `bar` but not the one with the same name in `foo`.
+
+There are other things KDevelop does well. Obviously, it highlights the source
+code in different colors; it has a customizable indenter; it has an integrated
+interface to the GNU debugger gdb; it can show you the documentation for a
+function if you hover the mouse over a use of this function; and many other
+neat things, some of which we will discuss below.
+
+The following description was written for KDevelop 4.2.x. I have found that
+KDevelop 4.0 and 4.1 were too buggy and crashed too often for a project the
+size of deal.II to be usable.
+
+**Note:** The [KDevelop manual](http://userbase.kde.org/KDevelop4/Manual) has much much more information on using KDevelop (the first version of the manual was generated by copying this page; I have written many more pages for the manual, however).
+
+## Setting up deal.II as a project in KDevelop
+
+### Terminology
+
+KDevelop has the concept of **sessions** and **projects**. A
+session contains all projects that have something to do with each other. For
+example, assume you are developing an application based on deal.II, then you
+would have a session in KDevelop that has two projects: both deal.II itself as
+well as your own application. If you also happen to be a gdb developer, then
+you would have a second session that contains gdb as a project. You could in
+principle have just one session for all of this, but you probably don't want
+gdb functions to be offered to you when you write a deal.II project.
+
+Another use for sessions is if you work both on the current development version of deal.II and/or your own project, as well as on a branch: in that case, you don't want KDevelop to confuse classes that belong to mainline and the branch, so you'd have two sessions, with the same set of projects but from different directories.
+
+### Setting up a session and deal.II as a project
+
+Let's say you want to develop with deal.II. Then you would first create a new
+session via the "Session" menu at the top left. Next, go to the "Project" menu
+to create deal.II as a project inside this session. To to this, follow these
+steps:
+
+
+  - Go to "Projects > Fetch project" to import a project
+  - Assuming you wanted to work with the current development sources of deal.II and don't already have a version checked out:
+    - In the dialog box, under "Select the source", choose to use "Subversion"
+    - Choose working directory
+    - Choose URL for source: http://www.dealii.org/svn/dealii/trunk/deal.II
+    - Hit "Get". This takes quite a long while; depending on the speed of your connection this can easily be 10 or more minutes. Unfortunately, in KDevelop 4.2.x the progress bar does not actually show anything, but you can track progress by periodically looking at the output of the command line command `du -sk /path/to/KDevelop/project` to see how much data has already been downloaded. (Note 1: The problem with the progress bar has been reported as [KDevelop bug 256832](http://bugs.kde.org/show_bug.cgi?id=256832). Note 2: In this process, I also get the error message "You need to specify a valid location for the project" which can be safely ignored.)
+  - It asks you to select a KDevelop project file in this directory. Since you probably don't have one yet, simply hit "Next"
+  - Hit "Next" again
+  - Choose the custom makefile project manager
+  - KDevelop will then start to parse the entire project. Again, it will take quite a while to go through all files and index classes etc. At the bottom right of the main window, there is a progress bar on the bottom right that shows how long this process has come along. (If you have several processor cores, you can accelerate this process by going to the "Settings > Configure KDevelop" menu item, then selecting "Background parser" on the left, and increasing the number of threads for background parsing on the right.)
+
+
+If you already have deal.II checked out from the repository or if you want to
+use a release version of deal.II that you have already unpacked in a
+directory, go through the same list as above but in step 2 choose "Do not
+obtain" under "Select the source" and instead just provide the path to the
+directory on your hard drive that you want to use.
+
+### Setting up an application as a second project
+
+The next thing you want to do is set up other projects using deal.II in the
+same session. For example, if you want to work on one of the tutorial programs
+(or another program that you have under the general deal.II directory tree,
+you would follow the same list of steps again but instead of fetching from a
+subversion repository you would select "Do not obtain" and just point KDevelop
+at the directory in which your project resides. If your project is in a
+directory elsewhere in your file system or you want to check it out from a
+repository, you should be able to follow the steps above as well.
+
+If you have multiple applications or libraries, simply repeat the steps to add
+more and more projects to your session.
+
+## KDevelop "tools": Working with source code
+
+'<img width="600px" src="http://www.dealii.org/images/wiki/Kdevelop-7.png" />'
+
+In order to work with projects, KDevelop has the concept of "tools". A tool
+provides a particular view of the source, or an action that can be taken with
+it. Tools are represented by buttons around the perimeter of your window (in
+vertical text along the left and right margins, or horizontally along the
+bottom margin). If you click on them, they expand to a subwindow within the
+main window; if you click on the tool button again, the subwindow disappears
+again. (Note: To make a subwindow disappear, you can also click at the "x" at
+the top right of the subwindow; however, at least with KDevelop 4.2.x, this
+also removes the button representing the tool from the perimeter, which was
+your way of getting the subwindow back. See below for how to get the button
+back onto the perimeter in the same way as getting any tool's button there. This behavior has been reported as
+[bug 270018](http://bugs.kde.org/show_bug.cgi?id=270018)). The picture on the right shows my own selection of tools, aligned on the left and right margins; in the picture, I have the "Classes" tool open on the left and the "Snippets" tool on the right, along with an editor for a source file in the middle. In practice, I find myself only having the editor and maybe the "Classes" or "Code Browser" tool open at the left; I only temporarily use the tools on the right, leaving me sufficient space for the editor.
+
+When you run KDevelop the first time, you should already have the "Projects"
+tool button. Click on it: it will open a subwindow that shows the projects you
+have added to the session at the bottom, and a file system view of the
+directories of your projects at the top.
+
+There are many other tools you can use with KDevelop, not all of which are
+initially present as buttons on the perimeter. To add some, go to the "Windows
+> Add tool view" menu entry. Here are a few useful ones I have added:
+
+  - **Classes**: A complete list of all classes that are defined in one of the projects or your session with all of their member functions and variables. Clicking on any of the members opens a source editor window at the location of the item you clicked on.
+  - **Documents**: Lists some of the more recently visited files, by kind (e.g. source files, patch files, plain text documents).
+  - **Code Browser**: Depending on your cursor position in a file, this tool shows things that are related. For example, if you are on an `#include` line, it shows information about the file you are including such as what classes are declared in that file; if you are on an empty line at file scope, it shows the classes and functions declared and defined in the current file (all as links: clicking on them brings you to the point in the file where the declaration or definition actually is); if you are in a function definition, it shows where the declaration is and offers a list of places where the function is used.
+  - **File system**: Shows you a tree view of the file system.
+  - **Documentation**: Allows you to search for man pages and other help documents.
+  - **Snippets**: This provides sequences of text that one uses over an over and doesn't want to write every time. For example, code like `for (typename Triangulation<dim>::active_cell_iterator cell = triangulation.begin_active(); cell != triangulation.end(); ++cell)` would make for a good snippet.
+  - **Konsole**: Opens a command line window inside KDevelop's main window, for the occasional command you may want to enter (e.g. to run `./configure`).
+
+Since for me vertical screen space is the most important, I have arranged my
+tool views at the left and right margin of the window. You can move a tool
+view by clicking on its symbol with the right mouse button.
+
+## Building (compiling) projects
+
+KDevelop doesn't know about autoconf, so you will have to run
+`./configure` by hand on a command line. If you have the
+**Konsole** tool as described above, you can even run
+`./configure` from a command line inside KDevelop.
+
+The next steps are to teach KDevelop about targets in your Makefiles. There
+are two ways to do that: selecting individual Makefile targets, and choosing a
+set of targets you may want to build frequently. For both approaches, open
+the "Projects" tool by clicking on the "Projects" button on the perimeter of
+KDevelop's main window (if you don't have this button see above how to add a
+tool's button there). The "Projects" tool window has two parts: the top half
+-- titled "Projects" -- lists all of your projects and let's you
+expand the underlying directory trees. The bottom half -- titled "Project
+Selection" -- lists a subset of those projects that will be built if you
+choose the menu item "Project > Build selection" or hit F8; we'll come back to
+this part below.
+
+### Building individual Makefile targets
+
+In the top part of the project view, expand the sub-tree for one project,
+let's say the deal.II project. This will give you icons for (i) directories
+under this project, (ii) files in the top-level directory for this project,
+(iii) Makefile targets KDevelop can identify. These categories are shown in the picture at right.
+
+'<img width="600px" src="http://www.dealii.org/images/wiki/Kdevelop-1a.png" />'
+
+To build any of the targets listed there, click on it with the right mouse button and select "Build". For example, doing this with the "clean" target will simply execute "make clean". You can see this happening in the subwindow titled "Build" that opens up, showing the command and the output. (This window corresponds to the "Build" tool, so you can close and later re-open the window using the "Build" tool button on the perimeter of the main window. It is shown at the bottom right of the picture on the right.)
+
+### Selecting a collection of Makefile targets for repeated building
+
+Right-clicking on individual Makefile targets every time you want to build
+something will quickly get old. Rather, we'd like to have individual targets
+for one or more of the projects in the session that we can repeatedly build
+without much mouse work. This is where the concept of "Build target
+selections" comes in: it is a collection of Makefile targets that are built
+one-after-the-other whenever you hit the "Build selection" button in the
+button list at the top, select the "Project > Build selection" menu item, or
+hit the F8 function key.
+
+The list of selected Makefile targets is shown in the bottom half of the
+"Projects" tool view.
+By default, the selection contains all projects, but you can change that. For
+example, if your list of projects contains deal.II and two of the tutorial
+programs, but you're currently only working on step-A, then you may want to
+remove step-B from the selection by highlighting it in the selection and
+hitting the red "-" button. Furthermore, you probably want to make sure that
+the deal.II project is built before the step-A project by moving entries in
+the selection up and down using the buttons to the right of the list.
+You can also get a particular Makefile target into the selection by
+right-clicking onto it and selecting "Add to buildset", or just highlighting
+it and hitting the green "+" button just above the list of selected targets.
+
+In the specific case of deal.II, Kdevelop's default of just calling "make"
+will not work: it will simply produce a screen with possible "make"
+targets. Consequently, you will want to remove the default "deal.II" project
+from the selection and instead add individual targets to the selection. If
+you're a deal.II developer, a useful target to add would be "all".
+
+KDevelop allows you to configure what to do whenever you build the
+selection. To this end, use the menu item "Project > Open
+configuration". There, you can for example select the number of simultaneous
+jobs "make" should execute -- if your computer has, say, 8 processor
+cores, then entering 8 in this field would be a useful choice. I don't enter
+anything as the "Default make target" since this would be a Makefile target used
+for **all** targets in the selection.
+
+### What to do with error messages
+
+If the compiler encounters an error message, simply click on the line with the error message and the editor will jump to the line (and if available column) where the error was reported. Depending on the error message, KDevelop may also offer you several possible actions to fix the error, for example by declaring a previously undeclared variable if an unknown symbol was found.
+
+## Running programs in KDevelop
+
+Once you have built a program, you will want to run it. To do this, you will want to configure "Launches" for your projects. A "Launch" consists of the name of an executable, a set of command line parameters, and an execution environment (such as "run this program in a shell", or "run this program in the debugger").
+
+'<img width="400px" src="http://www.dealii.org/images/wiki/Kdevelop-2.png" />'
+
+To set this up go to menu item "Run > Configure launches", highlight the project you want to add a launch for, and click on the red "+" button. Then enter the name of the executable, and the path where you want to run the program. If running the executable depends on building the executable and/or other libraries first, then you may want to add them to the list at the bottom: select "Build" from the dropdown menu, then hit the folder symbol to the right of the textbox and select whatever target you want to have built. In the example to the right, I have selected the target "all" from project "1.deal.II" and "step-32" from project "1.step-32" to make sure both the library and the application program have been compiled and are up to date before the program is actually executed. While you're there, you may as well also configure a debug launch by clicking on the "Debug" symbol and adding the name of the debugger program; if this is the system's default debugger (e.g. gdb on linux), then you don't need to do this step.
+
+'<img width="650px" src="http://www.dealii.org/images/wiki/Kdevelop-3.png" />'
+
+You can now try to run the program: Select "Run > Execute Launch" from the menu (or hit Shift-F9) and your program should run in a separate subwindow of KDevelop. The picture at the right shows the result: The new "Run" tool subwindow at the bottom shows the output of the program that is being run, in this case of the step-32 tutorial program.
+
+**Note:** If you have configured multiple launches, you can choose which one should run when you hit Shift-F9 by going to "Run > Current Launch Configuration". Unfortunately, by default, all launches are named "New Native Application" without an obvious possibility of renaming them, making it difficult to distinguish them when selecting the current launch configuration (see [KDevelop bug 272300](https://bugs.kde.org/show_bug.cgi?id=272300)). There is a way to edit the name of a configuration, however: in the dialog box you get when you select {{{Run > Current Launch Configuration}}}, double-click on the name of the configuration in the tree view on the left, which will allow you to edit the configuration's name.
+
+## Debugging programs in KDevelop
+
+Once you have a launch configured, you can also run it in a debugger: Select the menu item "Run > Debug Launch", or hit F9. If you are familiar with gdb, the effect is the same as starting gdb with the executable specified in the launch configuration and then saying "run". This means that if the program calls `abort()` somewhere (e.g. when you run onto a failing assertion) or if there is a segmentation fault, then the debugger will stop. On the other hand, if the program runs to the end (with or without doing the right thing) then the debugger will not stop by itself before the program is finished. In the latter case, you will want to set a breakpoint on all those lines of your code base where you want the debugger to stop before you run the debug launch. You can do that by moving the cursor on such a line and selecting the menu item "Run > Toggle breakpoint", or right-clicking on a line and selecting "Toggle breakpoint" from the context menu.
+
+'<img width="650px" src="http://www.dealii.org/images/wiki/Kdevelop-4.png" />'
+
+Running a program in the debugger will put KDevelop in a different mode: it will replace all the "Tool" buttons on the perimeter of the main window by ones that are appropriate for debugging, rather than for editing. You can see which of the mode you are in by looking at the top right of the window: there are tabs named "Review", "Debug", and "Code"; clicking on them allows you to switch back and forth between the three modes; each mode has a set of tool views of its own, which you can configure in the same way as we configured the "Code" tools above.
+
+Once the debugger stops (at a breakpoint, or a point where `abort()` is called) you can inspect a variety of information about your program. For example, in the image at the right, we have selected the "Frame stack" tool at the bottom (roughly equivalent to gdb's "backtrace" and "info threads" commands) that shows the various threads that are currently running in your program at the left (here a total of 8) and how execution got to the current stopping point at the right (here: `main()` called `run()`; the list would be longer had we stopped in a function called by `run()` itself). On the left, we can inspect local variables including the current object (the object pointed to by the `this` variable).
+
+From here, there are various possibilities you can do: You can execute the current line (F10, gdb's "next" command), step into the functions (F11, gdb's "step" command), or run to the end of the function (F12, gdb's "finish" command). At every stage, KDevelop updates the variables shown at the left to their current values. You can also hover the mouse over a symbol in your code, e.g. a variable; KDevelop will then show the current value of that symbol and offer to stop the program during execution the next time this variable's value changes. If you know gdb, you can also click on the "GDB" tool button at the bottom and have the possibility to enter gdb commands, for example in order to change the value of a variable (for which I have not yet found another way).
+
+## Other useful things
+
+### Customizing KDevelop to your needs
+
+There are a number of useful things one can configure in and around KDevelop's builtin editor. Of more universal use is to switch on line numbering using the menu entry "Editor > View > Show line numbers", making it easier to match compiler error messages or debug messages with locations in the code. In the same submenu you will probably also want to switch on the "Icon border" -- a column to the left of your code in which KDevelop will show icons such as whether there is a breakpoint on the current line.
+
+### = Keyboard shortcuts =
+
+KDevelop has an almost boundless list of keyboard shortcuts (some of them are listed below) that can be changed to your taste through the menu "Settings > Shortcuts". At the top of the dialog you can enter a searchword and it only shows those commands that match; you can then edit which key combination is bound to this command. Two that I have found to be very useful to change are to set "Align" to the "tab" key (I don't usually enter tabs by hand and rather prefer if me editor chooses the layout of code for me; with the changed shortcut, hitting "tab" makes KDevelop indent/outdent/align the code for me). The second one was putting "Toggle Breakpoint" on "Ctrl-B" since this is quite a frequent operation.
+
+### = Code indentation =
+
+On a more personal level, many of us like code formatted in a particular way. This, too, can be customized. To this end, go to the "Settings > Customize KDevelop" menu item, then click on "Source Formatter" on the left. You can choose one of the predefined indentation styles, or define your own one by adding a new style and then editing it. There is currently no way to exactly re-create the style in which deal.II sources have been indented in the past, but you can come close by using the settings for a new style that are shown in the two pictures below.
+
+
+'<img width="300px" src="http://www.dealii.org/images/wiki/Kdevelop-5.png" />'
+
+'<img width="300px" src="http://www.dealii.org/images/wiki/Kdevelop-6.png" />'
+
+
+**Note:** With KDevelop 4.2.2, you can create a new style for a particular mimetype (e.g. for C++ header files) but this style does not show up among the list of possible styles for other mimetypes (e.g. for C++ source files) although it would of course be useful to use the same style for both kinds of files. You will therefore have to define the style twice, once for header and once for source files. This has been reported as [KDevelop bug 272335](https://bugs.kde.org/show_bug.cgi?id=272335).
+
+### Useful keyboard commands
+
+I found the following key combinations useful, beyond the usual ones to open or save files, etc:
+
+<table border="1" cellspacing="0">
+<tr>
+<th colspan="2" style="background-color:#ffff99;"> Editing
+</th></tr>
+<tr>
+<th colspan="2"> Jumping around in code
+</th></tr>
+<tr>
+<td>       Ctrl-Alt-O
+</td><td> Quick open file: enter part of a filename and select among all the files in the current session's projects' directory trees that match the string; the file will then be opened
+</td></tr>
+<tr>
+<td>       Ctrl-Alt-C
+</td><td> Quick open class: enter part of a class name and select among all class names that match; the cursor will then jump to the class declaration
+</td></tr>
+<tr>
+<td>       Ctrl-Alt-M
+</td><td> Quick open function: enter part of a (member) function name and select among all names that match; note that the list shows both declarations and definitions and the cursor will then jump to the selected item
+</td></tr>
+<tr>
+<td>       Ctrl-Alt-Q
+</td><td> Universal quick open: type anything (file name, class name, function name) and get a list of anything that matches to select from
+</td></tr>
+<tr>
+<td>   Ctrl-Alt-N
+</td><td>Outline: Provide a list of all things that are happening in this file, e.g. class declarations and function definitions
+</td></tr>
+<tr>
+<td>   Ctrl-,
+</td><td>Jump to definition of a function if the cursor is currently on a function declaration
+</td></tr>
+<tr>
+<td>   Ctrl-.
+</td><td>Jump to declaration of a function or variable if the cursor is currently in a function definition
+</td></tr>
+<tr>
+<td>   Ctrl-Alt-PageDown
+</td><td>Jump to next function
+</td></tr>
+<tr>
+<td>   Ctrl-Alt-PageUp
+</td><td>Jump to previous function
+</td></tr>
+<tr>
+<td>   Ctrl-G
+</td><td>Goto line
+</td></tr>
+<tr>
+<th colspan="2"> Searching and replacing
+</th></tr>
+<tr>
+<td>   Ctrl-F
+</td><td>Find
+</td></tr>
+<tr>
+<td>   F3
+</td><td>Find next
+</td></tr>
+<tr>
+<td>   Ctrl-R
+</td><td>Replace
+</td></tr>
+<tr>
+<td>   Ctrl-Alt-F
+</td><td>Find-Replace in multiple files
+</td></tr>
+<tr>
+<th colspan="2"> Other things
+</th></tr>
+<tr>
+<td>   Ctrl-_
+</td><td>Collapse one level: remove this block from view, for example if you want to focus on the bigger picture within a function
+</td></tr>
+<tr>
+<td>   Ctrl-+
+</td><td>Expand one level: undo the collapsing
+</td></tr>
+<tr>
+<td>   Ctrl-D
+</td><td>Comment out selected text or current line
+</td></tr>
+<tr>
+<td>   Ctrl-Shift-D
+</td><td>Comment in selected text or current line
+</td></tr>
+<tr>
+<td>   Alt-Shift-D
+</td><td>Document the current function: move the cursor on a function or class declaration; hitting this key will already pre-populate a doxygen-style comment listing all parameters, return values, etc.
+</td></tr>
+<tr>
+<td>   Ctrl-T
+</td><td>Transpose the current and the previous character
+</td></tr>
+<tr>
+<td>   Ctrl-K
+</td><td>Delete the current line (not just emacs' "delete from here to the end of the line")
+</td></tr>
+<tr>
+<th colspan="2" style="background-color:#ffff99;"> Debugging
+</th></tr>
+<tr>
+<td>   F10
+</td><td> Step over (gdb's "next")
+</td></tr>
+<tr>
+<td>   F11
+</td><td> Step into (gdb's "step")
+</td></tr>
+<tr>
+<td>   F12
+</td><td> Step out of (gdb's "finish")
+</td></tr>
+
+<tr>
+<th colspan="2" style="background-color:#ffff99;"> Running a program
+</th></tr>
+<tr>
+<td>   F8
+</td><td> Build (call make)
+</td></tr>
+<tr>
+<td> Shift-F9
+</td><td> Run
+</td></tr>
+<tr>
+<td> F9
+</td><td> Run program in the debugger; you may want to set breakpoints beforehand, for example by right-clicking with the mouse on a particular line in the source code
+</td></tr></table>
+
+## Advanced topics
+
+### Working with subversion repositories
+
+If you are working with larger projects, chances are that the source code is managed by a version control system such as [subversion](http://subversion.apache.org). If the directory in which a project is located is under version control, KDevelop will automatically notice. (In other words: It is not necessary that you tell KDevelop to check out a copy itself when setting up your project; it is ok to point KDevelop at a directory into which you have previously checked out a copy from the repository.)
+
+
+If you have such a directory under version control, open the "Projects" tool view. There are then a number of things you can do:
+
+  - If your directory has become outdated, you can update it from the repository: Click on the project name with the right mouse button, go to the menu "Subversion" and select "Update". This will bring all files that belong to this project up to date with respect to the repository.
+
+  - If you want to restrict this action to individual subdirectories or files, then expand the tree view of this project to the level you want and right click on a subdirectory or file name, then do the same as above.
+
+'<img width="600px" src="http://www.dealii.org/images/wiki/Kdevelop-8.png" />'
+
+  - If you've edited one or more files, expand the view of this project to the directory in which these files are located and right click on the directory. This gives you a menu item "Subversion" that offers you different choices. Choose "Compare to base" to see the differences between the version you have edited and the version in the repository you had previously checked out. The resulting view will show the "diffs" for all files in this directory.
+
+  - If you only edited a single file, you can also get the "Subversion" menu by simply right clicking on the corresponding file name in the project view. Even simpler, just right clicking into the editor window will also give you this menu option.
+
+  - If you want to check one or more edited files in, right click either on an individual file, subdirectory, or whole project and select "Subversion > Commit". This will get you into "Review" mode, the third mode besides "Code" and "Debug" as you can see in the top right corner of the KDevelop main window. The picture on the right shows you how this looks. In review mode, the top part shows you diffs for the entire subdirectory/project and each individual changed file with changes highlighted (see the various tabs on this part of the window). By default, all changed files are in the changeset you are about to commit, but you can unselect some of the files if their modifications are unrelated to what you want to commit. For example, in the example on the right I have unselected `step-32.cc` and `step-32.prm` because the changes in these files have nothing to do with the other ones in this project and I don't yet want to check them in. After reviewing the changes you can enter a commit message into the text box and hit "Commit" on the right to send things off.
+
+  - As with seeing differences, if you want to check in a single file you can also just right click into the editor window to get the "Subversion > Commit" menu item.
+
+### Attaching the debugger to a running process
+
+'<img width="300px" src="http://www.dealii.org/images/wiki/Kdevelop-9.png" />'
+
+Sometimes, one wants to debug a program that's already running. One scenario for this is debugging parallel programs using MPI, see the section on this in the [Questions and Answers]]([Deal.II). To do this, go to the menu entry "Run > Attach to Process", which will open a window like the one on the right. You will want to select the program that matches your currently open project in KDevelop -- in my case that would be the step-32 tutorial program.
+
+This list of programs can be confusing because it is often long as in the case shown here. You can make your life a bit easier by going to the dropdown box at the top right of the window. The default value is "User processes", i.e. all programs that are run by any of the users currently logged into this machine (if this is your desktop or laptop, you're probably the only such user); it doesn't include processes run by the root user. You can limit the list by either choosing "Own processes", removing all the programs run by other users. Or better even: Select "Programs only", which removes a lot of processes that are formally running under your name but that you don't usually interact with, such as the window manager, background tasks and so on that are unlikely candidates for debugging.
+
+Once you have selected a process, attaching to it will get you into KDevelop's debug mode, open all the usual debugger tool views and stop the program at the position where it happened to be when you attached to it. You may then want to set breakpoints, viewpoints, or whatever else is necessary and continue program execution by going to the menu item "Run > Continue".
\ No newline at end of file
diff --git a/Build-Tests.md b/Build-Tests.md
new file mode 100644 (file)
index 0000000..945f403
--- /dev/null
@@ -0,0 +1,118 @@
+# A simple script and directory structure for running multiple build tests
+
+# Running build tests
+
+Running build tests with many different configurations is a vital part of testing the deal.II library. In particular before new releases, running on as many platformas as possible is important to make sure the new release is not broken.
+
+Therefore, we ask/encourage/beg everybody to check out the [build test page](http://www.dealii.org/cgi-bin/build.pl) and see if they have a configuration not listed there. In particular, operating systems and compilers are something the developers cannot provide in a wide range.
+
+If you decided to participate in build tests regularly, we provide a simple structure below, which helps you setting up these texts on a Unix based system (e.g. Linux, Mac OS X, Cygwin)
+
+# The code
+
+## Directory structure
+
+Create a directory, say `deal-test`, with the following entries:
+
+```
+deal-test
+--> branches
+--> configurations
+--> log
+```
+
+### The `branches` subdirectory
+
+In `branches` for instance do
+```
+svn checkout https://svn.dealii.org/trunk/deal.II trunk
+```
+or
+```
+svn checkout https://svn.dealii.org/branches/my_branch_name/deal.II my_branch
+```
+
+You can have as many branch checkouts there as you like.
+
+Now, we have expanded the structure to
+```
+deal-test
+--> branches
+----> trunk
+----> my_branch
+--> configurations
+--> log
+```
+
+### The `configurations` subdirectory
+
+Here, you can store configuration options in files named `**.conf`, which will be processed for each branch in `branches`.
+
+You can find an example configuration file [here](http://www.dealii.org/developer/development/Config.sample). It is not necessary to configure anything - an emtpy configuration file is equivalent to invoke `cmake` without any options.
+
+Now, the directory structure is extended to
+```
+deal-test
+--> branches
+----> trunk
+----> my_branch
+--> configurations
+----> disable-all.conf
+----> fortran-libs.conf
+----> fortran-mpi-multi.conf
+--> log
+```
+
+What's missing is the
+### Build test script
+
+This script expects to be called inside your `deal-test` directory. After the directory structure has been set up as above, there is just one configuration option left, namely the directory where the libraries will be built and discarded again. This is set in the variable `TMPDIR` at the very top of the script.
+
+```
+#!/bin/bash
+# set -e
+# set -u
+
+TMPDIR=/tmp
+
+echo Starting script at `date`
+dir=`pwd`
+
+for branch in branches/**; do
+  echo "Starting branch $branch"
+
+  pushd $branch > /dev/null
+  echo updating in `pwd`
+  svn update
+  popd > /dev/null
+
+  for file in configurations/**; do
+    pushd $branch > /dev/null
+    echo "Run build_test with configuration $file `date`"
+    ./contrib/utilities/build_test LOGDIR="$dir/log" CONFIGFILE="$dir/$file" MAKEOPTS="-j2"
+    popd > /dev/null
+
+    basename=$(basename $branch).$(basename $file)
+    logfile=$(ls -t1 log/$basename** | head -n 1)
+    echo "Mailing  " $branch $logfile `date`
+    echo $branch $basename $logfile
+    /usr/sbin/sendmail dealii.build.tests@gmail.com < $logfile
+    1. or and equivalent..
+    1. ssh mail mail dealii.build.tests@gmail.com < $logfile
+  done
+done
+```
+
+Copy this file into `deal-test/run-tests.sh` and everything is set up.
+
+You can just call
+```
+bash run-tests.sh
+```
+or you can add a line of the form
+```
+22 22 ** ** * (cd ~/deal-test; /bin/bash ~/deal-test/run-tests.sh >> ~/deal-test/LOG 2>&1 )
+```
+to your `crontab`.
+
+# Enjoy!
diff --git a/DoF-Handler.md b/DoF-Handler.md
new file mode 100644 (file)
index 0000000..ea2cc5a
--- /dev/null
@@ -0,0 +1,101 @@
+# Discussion of possible modifications to DoFHandler
+
+<!-- No auto-Table of Contents support! -->
+# Overview
+
+## Features desired from the application point-of-view
+
+  1. Loops over the following subsets of the hierachy of a Triangulation or a DoFHandler have to be efficient:
+    - active cells
+    - cells on a single level
+    - cells on all levels
+  1. Each cell accessor must be able to access efficiently:
+    - neighbors,
+    - children,
+    - subobjects of higher codimension.
+  1. As much information as possible should be generated algorithmically to avoid memory bandwith
+  1. More flexible mesh and dof enumeration structures to improve optimization options
+
+# Proposed Changes
+
+## Interface between meshes and `DoFHandler` objects
+
+### Geometry versus topology
+
+As a first proposal, the mesh geometry should be separated from the mesh topology, see [issue 1](https://github.com/dealii/dealii/issues#issue/1).
+
+<b>Note:</b> Some applications could make use of multi-leafed meshes, where one cell would have several neighbors at the same face. 
+
+### Detangling
+
+Currently, the DoFHandler copies the Triangulation structure to a large extend, in particular the fact, that cells are stored as a hierarchy, while objects with positive codimension are not. If a DoFHandler could be defined by an iterator range, then the current `DoFHandler` would be defined by the active iterators between begin_active() and end(), while `MGDoFHandler` would consist of a set of `DoFHandler`s defined buy the level ranges.
+
+**Warning!** We have to be able to exchange between levels as well as between an "active DoFHandler" and a "level DoFHandler"!
+It should be noted, that this technique wastes some memory. For instance, for the "active" DoFHandler, space is allocated for all cells in the hierarchy, even inactive and unused cells. This is a limited amount, which is probably not critical. Still, new interfaces can produce the same waste without impacting the library negatively (reducing waste being a bonus).
+
+Mesh accessors defining a DoFHandler as above must provide a unique identifier (integer) for each object (cell, codim1, codim2 to codimdim). This is needed to access the degrees of freedom of neighboring cells or of the positive codimension objects shared by a cell. It would be ideal if these identifiers were consecutive, but we might settle for the existing holes.
+
+Another important question to be settled is, whether we actually want to iterate over objects of positive codimension. I would assume that a lot simplifies if we do not. Currently, we cannot create FEValues without having a cell.
+
+Here a minimal mesh interface as it might be seen by the DoFHandler
+
+```
+template <int dim, int codim>
+class MeshAccessor
+{
+  public:
+  types::mesh_index index() const;
+
+  template<int diffdim>
+  MeshAccessor<dim,codim+diffdim>& sub_accessor(unsigned int number) const;
+  MeshAccessor<dim,codim>& child(unsigned int number) const;
+  // This one only if codim==0
+  MeshAccessor<dim,codim>& neighbor(unsigned int number) const;
+};
+```
+
+A few more functions may be needed to identify coarser neighbors.
+
+### First step
+
+In order to simplify DoFHandler implementations, we might decide to just implement the index function in the current triangulation accessors, which can be done comaprably cheaply.
+
+## Functionality of DoFHandler
+
+Currently, most of the actual implementation of DoFHandler is determined by DoFObjects (and its cousin hp::DoFObjects). This is also, where more flexible features can be implemented. Including the current ones, we have
+
+  1. `DoFObjects`, saving the same amount of dofs for each object of same type
+  1. `hp::DoFObjects`, saving different dofs and possibly several sets on each type
+  1. DoFObjects that only have to save the first dof on each cell etc. Here, we save a lot of memory access, but we do not allow renumbering inside a geometric object
+  1. DoFObjects for DG methods, which can be simpler than others
+
+A marriage between the current DoFObjects and hp::DoFObjects involves nothing more than a simple initialization of the latter with equally spaced blocks. This can be done in an afternoon. As for the other options, they extend the functionality and should be discussed for possible later implementation.
+
+### Access to level dofs and active dofs
+
+Currently, MGDoFAccessor (which is going to be reitred and superceded by DoFAccessor) has two functions to access degrees of freedom, get_dof_indices() and get_mg_dof_indices(), which makes writing generic loops a pain. Therefore, it is suggested to have a single function return either or. On a branch, we have such a function, together with a flag in DoFAccessor, which decides when to use which option.
+
+Alternatively, we continue having a separate Accessor/Iterator pair for level access, such that the begin functions would look like
+
+```
+class DoFHandler
+{
+  cell_iterator begin(active);
+  level_iterator begin(level);
+  level_iterator begin();
+};
+```
+
+As far as I can see, the regular dofs can only be accessed on active cells, so whenever we iterate through a single or all levels, it must be level dofs. Right?
+
+# Current obstacles
+
+## Closely entangled Trangulation and DoFHandler objects
+
+The structures in DoFHandler, namely DoFLevel and DoFFaces currently mirror the same structures in the Triangulation. This is a questionable practice, since none of the DoFHandler objects has the same hierarchical structure. DoFHandler and hp::DoFHandler only live on the finest level. MGDoFHandler has degrees of freedom on each level and thus duplicates them in vertices.
+On the other hand, the Triangulation structures are complicated and require a lot of specializations, which makes maintaining DoFHandler objects difficult.
+
+## Features which may not be beneficial
+
+DoFHandlers have a lot of iterators which may rarely be used, if at all. Raw iterators should not be used in applications and should not be public.
+Iterating over quads, lines, contradicts our paradigm of dimension independent programming.Therefore, the corresponding begin and send functions would be considered deprecated. This would reduce the amount of duplicated code considerably.
\ No newline at end of file
diff --git a/Eclipse.md b/Eclipse.md
new file mode 100644 (file)
index 0000000..b49510a
--- /dev/null
@@ -0,0 +1,460 @@
+# The Eclipse Integrated Development Environment and how to set up deal.II in it
+
+**Note: The following page is written with the CMake build system in mind that will be used starting with deal.II 8.0.**
+
+# About Eclipse
+
+[Eclipse](http://www.eclipse.org) is, today, the integrated development
+environment (IDE) that is likely most widely used around the world. It was
+originally developed for large-scale, industrial projects written in Java, but
+it has since been extended by plugins for virtually any other programming
+language, as well as many many modeling tools (for example, to name just one,
+for UML diagrams). For the purpose of deal.II, the C++ plugin (the
+[Eclipse CDT](http://www.eclipse.org/CDT)) is the basis for the steps described below. The advantages of using a modern IDE described at the top of the page on [are equally valid for Eclipse, or course.
+
+Eclipse with the C++ plug in included can be downloaded from the download page
+available via http://www.eclipse.org/ by choosing "Eclipse IDE for C/C++
+Developers". You will have to specify the operating system from the "download links"
+list to get the proper binaries for your operating system.
+Alternatively, a generic Eclipse can be used, but the Eclipse CDT (C/C++
+Development Tools, the C++ plugin for Eclipse) has then to be installed
+separately.
+
+Using an integrated development environment such as Eclipse is difficult to
+learn by just reading something about it. It's best learned by <i>doing</i> or
+watching someone else do it. To this end, take a look at training videos 7, 8
+and 25 at http://www.math.tamu.edu/~bangerth/videos.html .
+
+*Overview:*
+<wiki:toc />
+
+
+# A note up front on using Subversion and Eclipse
+
+If you will want to use subversion or some other version control system for the project you are about to set up, you first need to install the Eclipse plugin that can handle this -- installing the plugin later will not convert the project into one that uses subversion, even if the directories in which it is located have previously been created by subversion. See below about how to install the subversion plugin.
+
+
+
+# Setting up a project using deal.II by hand
+
+After starting Eclipse for the first time, you will be asked to choose a workspace. Accept the default. Then, you
+get a screen that provides you with a number of introductory options such as a
+tutorial, the help pages, etc. Take a look at these or click on the icon to
+get to the Workspace right away (where you will also land when calling Eclipse
+for the second or later times). Then follow these steps, shown below taking the
+step-22 tutorial as an example of any free-standing program that uses deal.II
+(these steps are also demonstrated in video #7 linked to above):
+
+  - Create the Eclipse project:
+    - From the main menu bar select: "File > New > Makefile Project with Existing Code" (alternatively, you can use the right-click context menu in the "Project Explorer" sub-window on the left)
+    - Browse for the directory which has the code of your project, `examples/step-22` in this example, select "Linux GCC" as the "Toolchain for Indexer Settings", then press Finish.
+    The project now exists for Eclipse, and it should allow you to edit files,
+    use auto-completion, etc. Go ahead by either opening by hand one of your
+    project's `.cc` files or by hitting Shift-Ctrl-R and start typing the
+    name of one of your files, for example in the current context
+    `step-22.cc`. This should open the file and allow you to edit it.
+    However, Eclipse will show swiggly lines under
+    any deal.II symbol, the deal.II header files, etc. The next step is to
+    teach Eclipse where to find the deal.II header files so that it knows
+    about the deal.II classes, functions, etc. To this end, right-click on the
+    newly created project in the "Project Explorer" subwindow on the left and
+    choose "Properties" at the very bottom. Then:
+    - Select "C/C++ General > Paths and Symbols" by expanding the tree view under "C/C++ General"
+    - Select "GNU C++" and click on "Add..." on the right
+    - Select "Add to all languages", just to be on the safe side
+    - From the "File system..." select the include directory of an installed version of deal.II
+    - Click "OK" as often as necessary to close all dialog windows.
+    - If your project depends on other external libraries, you may wish to repeat this step for all include file directories of these projects.
+    Eclipse should have removed the swirly lines from under all header files, but it will likely not recognize the deal.II classes and functions yet, as indicated by the lines under these names and the red marks at the right margin of the editor sub-window. To achieve this, just close the editor sub-window and open the file again. You can test that Eclipse has found everything by putting the cursor into the editor window where you opened step-22.cc and in one of the member functions start typing something like `triangulation.exec` and then hitting Ctrl-Space to see what auto-completions Eclipse proposes. It should, among others, at least propose `triangulation.execute_coarsening_and_refinement` based on its knowledge that the member variable `triangulation` is of type `Triangulation<dim>`.
+
+*Note:* Eclipse will use a _very large amount_ of memory to index all of the
+symbols deal.II provides, on the order of several gigabyte. If you do not have
+that much memory, you can limit how much it uses by excluding the
+`include/deal.II/bundled` directory from indexing, which may contain in
+particular the BOOST header files that are exceedingly large. This can be done
+with a _resource filer_, as described at
+http://help.eclipse.org/kepler/index.jsp?topic=/org.eclipse.platform.doc.user/concepts/resourcefilters.htm .
+
+The next step is to teach Eclipse how to compile your project. To this end, it needs a Makefile. If you are writing the Makefile yourself, all is well. If you are using CMake to build your project in the same directory as the source files are (that's the setup we use for the tutorial programs), then you need to run CMake first to produce a Makefile. These are the next steps then:
+
+  - Configure the build:
+    - As above, highlight the new "step-22" project, then go to "Project > Make target > Create" and enter "step-22" into the respective dialog field.
+    - Alternatively, you can right-click on the "step-22" project name in the left sub-window and go to the "Make targets > Create" entry.
+    - Afterwards select "Project > Properties" from the main menu bar and in the corresponding dialog select "C/C++ Build" from the left panel (i.e., the actual entry, not the down-arrow next to it). Then select the "Behaviour" tab to set the desired build target, here "step-22", at "Build (incremental Build)" text box. The correct entry for "Clean" is simply "clean" (this is used to remove all generated files in this directory).
+
+
+  - Configuring the binary to run and debug ("launches"):
+    - From the main menu bar select: "Run > Run configurations" to open the "Run Configuration" window
+    - From the window, double click "C/C++ Application" on the left panel to create a new run configuration, or highlight "C/C++ Application" and click on the hardly-recognizable "New launch configuration" button at the top of the selection list on the left. Then, unless it is already there, type the executable name that is produced by the Makefile in the field "C/C++ Application", again "step-22" in this example.
+    - If you have an application that requires an input file, then the name of this input file can be entered in the other tabs.
+    - Close the dialog, and test whether the application runs as intended by clicking on the green right triangle button at the top of the primary window, roughly in the middle. The output of the program should again appear in the "Console" tab of the subwindow at the bottom.
+
+At this point you should have a complete project you can edit, compile and run. The screen should look roughly like this after opening the step-22.cc file (my project names are prefixed with the name of the machine, thus the "ultra450." prefix to everything; also, when I created this snapshot, I had not set the include paths correctly and the red swirly lines under many symbols should not be there for you):
+
+'<img width="800px" src="http://www.dealii.org/images/wiki/Eclipse-2.png" align="center" />'
+
+
+# Debugging with Eclipse
+
+Once you have set up a launch configuration for an application as described above, you can also debug this application. (One of the video lectures referenced above also shows you how to do this.) To this end, hit the small green "Bug" icon just to the left of the "Run" icon described above. This will build the executable (if it isn't up to date) and then move all of Eclipse into "Debug Perspective", as shown here:
+
+'<img width="800px" src="http://www.dealii.org/images/wiki/Eclipse-3.png" align="center" />'
+
+<br>
+
+"Debug perspective" gives you an entirely different view on the program as the "Code perspective" you have seen before. (You can toggle between the two perspectives using the icons at the top right of the Eclipse main window.) In particular, what you primarily get to see is the call stack at the top left, a view of all local variables at the top right, the source at the center left, an outline of the current file at the center right, and the console output of your program at the bottom. All of these sub-windows can be resized, of course. Some of these sub-windows have other tabs as well that you can explore, and if you don't need one sub-window for a moment, then click on the triangle pointing down to minimize it -- it will end up as an icon at the left margin, right margin, or bottom right of the main window (depending on where the sub-window was located before) from where it can be restored.
+
+Using the symbols in the "Debug" sub-window at the top left (or the menu entries and corresponding keyboard shortcuts listed in the "Run" menu"), you can now step through the program, inspect the current state of your program at the top right by observing the values of local variables, and set breakpoints by going to certain source locations and right clicking onto the code line you want to set a breakpoint on.
+
+
+# Setting up a project using deal.II with CMake help
+
+An alternative to get Eclipse to understand your project is to let CMake generate an Eclipse project for you, assuming you are using CMake. To this end, go to the source directory (using the `step-22` example again) and say
+```
+  cmake -G"Eclipse CDT4 - Unix Makefiles" -DDEAL_II_DIR=/path/to/deal.II .
+```
+This generates not only a Unix Makefile, but also an Eclipse project file. You can get Eclipse to use it by selecting from the menu "File > Import...", then choosing "General > Existing Projects into Workspace". Click on "Next", and in the next dialog window select as the root directory the directory where you ran CMake above. After selecting this directory, Eclipse should show you the name of the project under "Projects". Simply click on "Finish" to let Eclipse choose it. It will then automatically know where to find header files, about build targets, etc.
+
+To build the executable, go to the "Make target" tab (usually located in the right sub-window) and double-click on "all". In the "Console" tab (usually located in the bottom sub-window) you can view the commands being executed to build your program.
+
+You may still have to set up run and debug launches if you want to run or debug the executable so built, however.
+
+# Setting up deal.II as a development project in itself
+
+If you want to work on the deal.II sources themselves, rather than just use
+them for your own project, then use the following steps:
+
+  - Select menu item "File > New... > Makefile project with existing code" and in the dialog that opens give the project a name (e.g., "deal.II") and enter or select the path to the deal.II directory into which you have previously unpacked the library. In the "Toolchain for Indexer Settings" select "Linux GCC". Then click "Finish".
+
+You will notice that an icon for the next project has appeared in the "Project Explorer" sub-window on the left side of the Eclipse main window. The icon can be expanded using the little down-arrow on its left to see the directory tree underneath and you can try to go down into it to open a file just to see how it works. You will also notice that a progress bar at the center bottom of the Eclipse window is indicating that Eclipse is reading and parsing all the files in this directory tree so that the editor can offer you auto-completion and similar things.
+
+*Note 1:* The steps above only set up deal.II as a project inside Eclipse,
+allowing you to edit files and telling Eclipse where to find symbols so that
+things like auto-completion work. However, they do not allow you to build
+and install deal.II from inside Eclipse. Eclipse does in principle allow you
+to set up these things (see above, for how to do this on a project that
+<i>uses</i> deal.II), but it is difficult to do when building in a directory
+other than where the source files are located, as we suggest in the deal.II
+installation instructions. Consequently, if you want to <i>develop deal.II,
+not just use it</i>, then you still want to build and install from the command
+line.
+
+*Note 2:* The steps above allow you to use Eclipse to edit deal.II files and
+most of it will work just as expected. However, there is one snag: some parts
+of the code of deal.II is guarded by things like
+```
+  #ifdef DEAL_II_WITH_TRILINOS
+  ...
+  #endif
+```
+In particular, this is the case for all of the Trilinos and PETSc wrappers,
+and parts of the MPI stuff. The problem is that whether this preprocessor
+symbol is defined or not is something that can not be determined by looking at
+the <i>source</i> directory we have taught Eclipse about: it is something that
+is determined in a file `config.h` in the <i>build</i> directory (of which
+there may in fact be
+more than one per source directory). Consequently, by default, Eclipse doesn't
+see the `#define DEAL_II_WITH_TRILINOS` anywhere and thus never offers you to
+auto-complete any of the Trilinos, PETSc or MPI stuff. This is annoying. If
+you want to develop stuff where this is an obstacle, you can provide Eclipse
+with additional include paths to search, as explained above when setting up
+external projects. You can do this to provide Eclipse with a path where it can
+find a `deal.II/base/config.h` file (typically, the install directory where you
+install the version you are currently developing) that has the requisite
+`#define`s so that Eclipse also provides you with information about the
+otherwise unavailable classes.
+
+  - The next step is to set up deal.II as a project Eclipse knows how to compile. To this end, select (highlight) the deal.II project with the mouse in the "Project Explorer" sub-window. Then go to "Project > Make Target > Create" and enter a Makefile target name. You can get the existing target names by running *make* on the command line in the deal.II directory -- the two most common ones are "all" and "online-doc", along with "debug" and "optimized". You can repeat creating targets several times.
+
+  - To see which targets now exist for Eclipse, note the "Make targets" tab in the right sub-window (the other tabs are "Outline" and "Task list", unless you have added more tabs to this sub-window using "Window > Show view").
+
+  - You can let Eclipse build a particular target by double-clicking on a target. The corresponding output of the *make* command and the compilers it calls will then end up in the "Console" tab in the bottom sub-window.
+
+Everything you've done so far is visible in the following screenshot:
+
+
+'<img width="800px" src="http://www.dealii.org/images/wiki/Eclipse-1.png" align="center" />'
+
+<br>
+
+*Note:* If a particular tab of a sub-window is not where you expect it, look around in the other sub-windows. They can be drag-and-dropped into the place where you want them to be. If they're not there altogether, take a look at the list of views in the "Window > Show view" menu entry for what's avaiable!
+
+A final, useful, modification if you have more than one processor in your system is to enable parallel builds. To this end, select the menu entry "Project > Properties...", then select "C/C++ Build" and in the "Builder Settings" tab uncheck the box that says "Use default build command". This enables editing the text field that follows and allows you to replace the default command *make* by *make -j8*, for example if you want to compile with 8 parallel compile jobs.
+
+
+
+# Some useful keyboard shortcuts
+
+I found the following key combinations useful, beyond the usual ones to open or save files, etc:
+
+
+<table border="1" cellspacing="0">
+<tr>
+<th colspan="2" style="background-color:#ffff99;"> Editing
+</th></tr>
+<tr>
+<th colspan="2"> Jumping around in code
+</th></tr>
+<tr>
+<td>       Ctrl-Shift-R
+</td><td> Open resource: type the name of a file and get it opened. Note that the search window allows you to use wildcards such as `*` if you only want to type part of a name.
+</td></tr>
+<tr>
+<td>       Ctrl-Shift-H
+</td><td> Open type: type the name of a type/class and get it opened. Note that the search window allows you to use wildcards such as `*` if you only want to type part of a name.
+</td></tr>
+<tr>
+<td>       Ctrl-Shift-T
+</td><td> Open element: type anything (class name, function name) and get a list of anything that matches to select from
+</td></tr>
+<tr>
+<td>       Ctrl-Alt-I
+</td><td> Open the include browser: Show a list of all include files used in the current file. Right clicking on any of the shown include files allows opening them.
+</td></tr>
+<tr>
+<td>   Ctrl-O
+</td><td>Outline: Provide a list of all things that are happening in this file, e.g. class declarations and function definitions, include directives, etc; the dialog that appears allows you to start typing a name, reducing the list to all those that match.
+</td></tr>
+<tr>
+<td>   F3
+</td><td>Jump to declaration of a function or variable if the cursor is currently in a function definition
+</td></tr>
+<tr>
+<td>   Ctrl-Shift-Down
+</td><td>Jump to next function
+</td></tr>
+<tr>
+<td>   Ctrl-Shift-Up
+</td><td>Jump to previous function
+</td></tr>
+<tr>
+<td>   Ctrl-L
+</td><td>Goto line
+</td></tr>
+<tr>
+<td>   Crtl-W
+</td><td> Closes current "tab".
+</td></tr>
+<tr>
+<td>   Alt-Left
+</td><td>Jump to previous used "tab". This even opens a previously closed file.
+</td></tr>
+<tr>
+<td>   Alt-Right
+</td><td>Jump to next "tab"
+</td></tr>
+<tr>
+<th colspan="2"> Searching and replacing
+</th></tr>
+<tr>
+<td>   Ctrl-J
+</td><td>Incremental find: start typing and see what fits so far
+</td></tr>
+<tr>
+<td>   Ctrl-F
+</td><td>Find and find/replace
+</td></tr>
+<tr>
+<td>   Ctrl-K
+</td><td>Find next
+</td></tr>
+<tr>
+<th colspan="2"> Other things
+</th></tr>
+<tr>
+<td>   Ctrl-Space
+</td><td>Call auto-completion assistant
+</td></tr>
+<tr>
+<td>   Alt-/
+</td><td>Auto-complete. If multiple names match the already typed text, then you can cycle through them by hitting Alt-/ multiple times.
+</td></tr>
+<tr>
+<td>   Ctrl-Shift-Space
+</td><td>In an expression of the form "object.member()" or "function()" with the cursor in the parentheses, opens a context menu that shows the order and types of arguments that go there.
+</td></tr>
+<tr>
+<td>   Ctrl-/
+</td><td>Comment in/out selected text or current line
+</td></tr>
+<tr>
+<td>   Ctrl-Shift-F
+</td><td>Automatic indent highlighted lines of code.
+</td></tr>
+<tr>
+<th colspan="2" style="background-color:#ffff99;"> Debugging
+</th></tr>
+<tr>
+<td>   F6
+</td><td> Step over (gdb's "next")
+</td></tr>
+<tr>
+<td>   F5
+</td><td> Step into (gdb's "step")
+</td></tr>
+<tr>
+<td>   F7
+</td><td> Step return (gdb's "finish")
+</td></tr>
+<tr>
+<td>   F8
+</td><td> Resume (gdb's "continue")
+</td></tr>
+
+<tr>
+<th colspan="2" style="background-color:#ffff99;"> Running a program
+</th></tr>
+<tr>
+<td>   Ctrl-B
+</td><td> Build (call make)
+</td></tr>
+<tr>
+<td> Ctrl-F11
+</td><td> Run
+</td></tr>
+<tr>
+<td> F11
+</td><td> Run program in the debugger; you may want to set breakpoints beforehand, for example by right-clicking with the mouse on the left sub-window margin next to a particular line in the source code
+</td></tr>
+<tr>
+<th colspan="2" style="background-color:#ffff99;"> Working with subversion (works both in file editors as well as the C/C++ project view)
+</th></tr>
+<tr>
+<td> Ctrl-Alt-L
+</td><td> Show diffs
+</td></tr>
+<tr>
+<td> Ctrl-Alt-C
+</td><td> Commit
+</td></tr>
+<tr>
+<td> Ctrl-Alt-U
+</td><td> Update from repository
+</td></tr>
+<tr>
+<td> Ctrl-Alt-P
+</td><td> Create a patch from local changes
+</td></tr></table>
+
+# Configuring Eclipse
+
+Eclipse can be configured in a myriad different ways, to the point where one sometimes finds oneself wishing that there were less bells and whistles. Be that as it may, there are many useful things that may take a while to discover but that really make life easier. Below is a list of things that integrate working with big software projects like deal.II better into the existing workflows of version control, documentation, etc.
+
+
+## Showing line numbers and dealing with tabs
+
+Since deal.II assertions show which line of a file triggered an error, it is often useful to configure Eclipse to show line numbers next to each line of a file that's open in an editor. To do this, go to "Window > Preferences", then select the down-arrow of "General", in the sub-tree that then expands select the down-arrow next to "Editors" and click on "Text editor". In the dialog to the right of the window, click the checkbox called "Show line numbers".
+
+'<img width="400px" src="http://www.dealii.org/images/wiki/Eclipse-line-numbers.png" align="center">'
+
+<br>
+
+In the same dialog, there is also a setting for the tab width. In the deal.II source code, we use a tab width of 8, but Eclipse by default uses 4, leading to an occasionally awkward display of indentation levels. Thus, set it to 8. Finally, since different editors have a habit of interpreting the tab size differently (some assume that a tab equals 4 spaces, whereas others assume 8), it is worthwhile to simply disable the use of tabs altogether when editing code, and letting the editor fill any space it encounters using spaces. For this, check "Insert spaces for tabs".
+
+
+## Enabling code folding
+
+Some people really like the editor to fold in code they aren't working on right now so that only that part that's relevant for the moment is visible (others just excessively use the "Outline" facility using the Ctrl-O shortcut). By default, the Eclipse folding settings are a bit awkward since it doesn't want to fold a whole lot, but this (like everything else) can be configured. To this end, go to "Window > Preferences" and select the C/C++ tab and under it the "Editor > Folding" sub-tab. You can select which regions of a code can be folded:
+
+'<img width="400px" src="http://www.dealii.org/images/wiki/Eclipse-folding-assistant.png" align="center" />'
+
+The buttons under "Initially fold these region types" allow you to set which regions should be folded in whenever you open a file the first time; I have chosen to see the entire file but you can obviously choose a different set.
+
+Once selected as above, you can fold in or out certain parts of the code by clicking on the little "-" or "+" buttons in the gray area on the left side of an editor window, right next to line numbers if you have enabled them as shown above.
+
+
+## Integrating Eclipse and Subversion
+
+deal.II and many of its subprojects use [http://subversion.apache.org Subversion]([KDevelop]]) as the Version Control System of choice. Eclipse has a plugin that allows using Subversion for all the files one wants to work on; the plugin is called **Subversive** and you need to install it before creating any project (see above) you want to use this plugin for.
+
+In order to install Subversive, go to menu entry "Help > Install new software" and choose the site in the "Work with" dialog at which the plugins for this version of Eclipse can be obtained. At the time of writing this text Indigo was the current Eclipse version,  and the site was "Indigo - http://download.eclipse.org/releases/indigo". It takes a while (a couple of minutes on my system) for Eclipse to figure out all the packages that are available but when it does you should be able to find the Subversive packages in the "Collaboration" tab that you can expand using the down arrow. Select them all and then hit the appropriate buttons to get them installed. Half-way through the process, Eclipse will ask you which "Subversive Connector" you want to install. These connectors are apparently specific for the particular subversion release you have (which you can find out by calling `svn --version` on the command line). Pick the one that matches your version best.
+
+Once you have the Subversive plugin installed, create an Eclipse project as discussed at the top of this page. The project explorer panel should then look somewhat like this, displaying the revision number next to each file or directory:
+
+'<img width="400px" src="http://www.dealii.org/images/wiki/Eclipse-subversive-1.png" align="center" />'
+
+All the usual subversion operations (adding a file or directory, updating it from the repository, committing, diffing, annotating, or showing a history) can then be obtained through one of two ways:
+
+  - If you are in an editor window, right click into the window to get the context menu and from there go to the sub-menu called "Team".
+  - Right-clicking on a file or directory in the "Project Explorer" panel on the left (i.e., the one shown above) and then again selecting the sub-menu "Team".
+
+Maybe confusingly, however, the option to see the diffs of a file/directory against the one that's in the repository is not found in the "Team" sub-menu, but in the "Compare with" sub-menu.
+
+## Integrating Eclipse and Doxygen
+
+[Doxygen](http://www.doxygen.org/) is one of the most important tools for generating high quality documentation for C++ software, and it is <em>the</em> tool by which all of deal.II's documentation is generated. Thus, it would be nice if Eclipse could help write this documentation, and indeed it can. To this end, tell Eclipse that we want to be able to write Doxygen comments, by going to the "Window > Preference" menu entry and then selecting the  "C/C++" tab and "Editor" subtab as shown here:
+
+'<img width="400px" src="http://www.dealii.org/images/wiki/Eclipse-doxygen.png" align="center" />'
+
+Then select "Doxygen" as the "Documentation tool" in the bottom part of the panel on the right, as shown above.
+
+With this setting so chosen, we can start editing and see how it can help us. To this end, let's assume we have written the following function declaration:
+
+'<img width="800px" src="http://www.dealii.org/images/wiki/Eclipse-doxygen1.png" align="center" />'
+
+We may want to document it using the usual Doxygen markup. So go to the line before the function, type `/**` and hit enter. Eclipse will then automatically expand the comment to the following:
+
+'<img width="800px" src="http://www.dealii.org/images/wiki/Eclipse-doxygen2.png" align="center" />'
+
+You can then start filling in the documentation for the function as a whole, the two function arguments, and the return type, using all the markup options Doxygen provides.
+
+## Code style issues
+
+Eclipse can be configured in more ways than one can count. One issue is to configure the indentation style. As a historical accident, deal.II is using an indentation style that doesn't match pretty much any other style that is around, but it can be approximated using Eclipse's settings. To this end:
+  - Highlight the deal.II project you have created above in the "Project Explorer" sub-window.
+  - Go to "Project > Properties" from the main menu, or right-click on the project and choose "Properties" in the context menu.
+  - Then go to expand the "C/C++ General" sub-tree by clicking on the down arrow next to it and select "Code style".
+  - In the panel on the right, you can click on "Configure Workspace Settings..." to get a dialog in which you can edit an existing coding style or create a new one.
+  - You can import the following style: [stylefile.xml](https://docs.google.com/open?id=0B1_zqLUYjm2ea1c0Y1VTdmJHNUU)
+  - Alternatively create a new one and choose the "GNU" style as the basis for this new style and follow the instructions below.
+
+Modify the entries under the various tabs of this dialog as shown in the following set of pictures (click on the pictures to get larger versions):
+
+'<img width="800px" src="http://www.dealii.org/images/wiki/Eclipse-code-indentation-3.png" align="left" />'
+
+'<img width="800px" src="http://www.dealii.org/images/wiki/Eclipse-code-indentation-4.png" align="right" />'
+
+'<img width="800px" src="http://www.dealii.org/images/wiki/Eclipse-code-indentation-5.png" align="left" />'
+
+'<img width="800px" src="http://www.dealii.org/images/wiki/Eclipse-code-indentation-6.png" align="right" />'
+
+'<img width="800px" src="http://www.dealii.org/images/wiki/Eclipse-code-indentation-7.png" align="left" />'
+
+'<img width="800px" src="http://www.dealii.org/images/wiki/Eclipse-code-indentation-8.png" align="right" />'
+
+'<img width="800px" src="http://www.dealii.org/images/wiki/Eclipse-code-indentation-9.png" align="left" />'
+
+'<img width="800px" src="http://www.dealii.org/images/wiki/Eclipse-code-indentation-10.png" align="right" />'
+
+'<img width="800px" src="http://www.dealii.org/images/wiki/Eclipse-code-indentation-11.png" align="left" />'
+
+# Setting up Eclipse with Parallel Tools Platform (PTP)
+
+Section currently under development. Please be patient.
+## What PTP is?
+
+[PTP](http://www.eclipse.org/ptp/) is set of tool for developing, debugging and profiling MPI applications. Instructions for installation into existing Eclipse can be found [here](http://www.eclipse.org/ptp/downloads.php). Make sure you're trying to install correct PTP version for your Eclipse (7.0 for Kepler, 6.0 for Juno, 5.0 for Indigo). Most of installation issues are described in PTP release notes [v.7.0](http://wiki.eclipse.org/PTP/release_notes/7.0). 
+## Installing from package
+
+This instructions have been tested under Ubuntu 12.04
+If you were not able to install PTP into exesting  Eclipse (or you can't find PTP perspectives in Window->Show Perspective -> Other  - it sometimes happens), maybe it would be easier to download a complete package from [Eclipse download site](http://www.eclipse.org/downloads/).  "Eclipse for Parallel Application Developers Eclipse for Parallel Application Developers" is package that you have to download. Untar it wherever you want, open terminal, navigate to Eclipse folder and run ./eclipse (it is safe to do it this way - to make sure that Eclipse has same environmental variables as in terminal).
+## SDM - Scalable debug manager
+
+Debugging parallel program is not easy - especially when the error occurs only in parallel executions. SDM allows debugging parallel programs in similar way that standard Eclipse debugger can help you improve  non-mpi applications. To use SDM you have to install it on target machine. [Here](http://wiki.eclipse.org/PTP/release_notes/7.0#Install_optional_PTP_debugger_component) are instructions how to do it. Compiling from source should work (tested on Ubuntu), but if you have some trouble with it, you should find compiled PTP in ptp-sdm-7.0.x.zip  package from here: [http://download.eclipse.org/tools/ptp/updates/kepler] (directory sdm/org.eclipse.ptp.OS_7.0.x.yyyymmddhhmm , where  OS is operating system and 7.0.x.yyyymmddhhmm is PTP release ).
+## Setting up project with parallel run configuration
+
+Set up you project in the same way as for standard deal.II programs. If you have workspace folder from other versions of Eclipse you can reuse it. Now you will only have to configure parallel runs.
+### Local projects (only with Eclipse Kepler with PTP 7.x)
+
+Go to Run->Run Configurations. Select Parallel Application and click on "New lauch configuration"(PICTURE). Specify your MPI version from drop-down list and select Local in connection type. You will be asked to confirm connection to local system, click Yes.(PICTURE) Now there will be some other option available: (PICTURE)
+Go to applications and specify executable in "Application program". Click "Apply". Now you can test your configuration by pressing "Run", or just click "Close".  New run configuration will appear in drop-down menu near Run button at the top of a screen.
+
+If you run configuration is working, you can set up debugger. Go to Run->Debug Configurations. In Parallel Applications will be your run configuration. Now you only have to set SDM executable path - go to Debugger tab.(PICTURE) If you have installed SDM with custom prefix, specify path to SDM. Number of MPI processes can be increased in Resources tab.
+
+## Debugging parallel program
+
+From drop-down list near bug icon select your debug configuration. You will be asked to confirm opening Parallel Debug perspective, click yes. The following view will appear: (PICTURE)
+
+The main difference between default Eclipse debugger is "Parallel Debug" tab. The diamonds represents processes, green means that process is running, yellow - suspended, red -terminated. You can select one process by double click. Black square indicates if process is selected, only selected processes are displayed in "Debug" tab. From Debug tab you can debug each process like serial one, you can also suspend group of processes in "Parallel Debug" tab. 
+
+More informations can be found in PTP help and tutorials.
\ No newline at end of file
diff --git a/Frequently-Asked-Questions.md b/Frequently-Asked-Questions.md
new file mode 100644 (file)
index 0000000..9727ad1
--- /dev/null
@@ -0,0 +1,1505 @@
+# Frequently Asked Questions
+
+<!-- No auto-Table of Contents support! -->
+
+# General questions on deal.II
+
+## Can I use/implement triangles/tetrahedra in deal.II?
+
+This is truly one of the most frequently asked questions. The short answer is:
+No, you can't. deal.II's basic data structures are too much
+tailored to quadrilaterals and hexahedra to make this trivially possible. Implementing other reference cells such as triangles and tetrahedra
+amounts to re-implementing nearly all grid and DoF classes from
+scratch, along with the finite element shape functions, mappings, quadratures and a whole host of other things. Make triangles and tetrahedra work would certainly involve having to write several ten thousand lines of code, and to make it usable in all the rest of the library would require auditing a very significant fraction of the 600,000 lines of code that make up deal.II today.
+
+That said, the current specialization on quadrilaterals and
+hexahedra has two very positive aspects:
+First, quadrilaterals and hexahedra typically provide a significantly better approximation quality than triangular meshes with the same number of degrees of freedom; you therefore get more accurate solutions for the same amount of work.
+Secondly, because the shape of cells are known, we can make a lot of things known to the compiler (such as the number of iterations of a loop over all vertices of a cell) which avoid a large number of run-time computations and makes
+the library as fast as it is. A simple example is that in deal.II we know that a loop over all vertices of a cell has exactly `GeometryInfo<dim>::vertices_per_cell` iterations, a number that is known to the compiler at compile-time. If we allowed both triangles and quadrilaterals, the loop would have `cell->n_vertices()` iterations, but this would in general not be known at compile time and consequently not allow the compiler to optimize on.
+
+If you do need to work with a geometry for which all you have is a triangular or tetrahedral mesh, then you can convert this mesh into one that consists of quadrilaterals and hexahedra using the `tethex` program, see http://code.google.com/p/tethex/wiki/Tethex .
+
+## I'm stuck!
+
+Further down below on this page (in the debugging section) we list a number of strategies on how to find errors in your program. If your question is how to implement something new for which you don't know where to start, have you taken a look at the set of tutorial programs and checked whether one or the other already has something that's close to what you want?
+
+That said, there will be situations where documentation doesn't help and where you need other someone else's opinion. That's what the [deal.II mailing lists](http://dealii.org/mail.html) are there for: Feel free to ask! You may also wish to subscribe to the users' list -- not so much because someone else might ask the same question you have, but because reading the list gives you background information on things others are working on that may help you when you want to do something similar.
+
+When asking for help on the mailing list, be specific. We frequently get mail of the following kind:
+<pre>
+  I'm trying to do X. This works fine but it fails when I try to transfer
+  the data to my MyClass::Estimator object. I tried to use something similar
+  to what's done in a couple of tutorial programs but it doesn't work. I'm
+  new at C++ and I just can't seem to get the syntax right.
+</pre>
+
+This message doesn't contain nearly enough information for anyone to really help you: we don't know what `MyClass::Estimator` is, we don't know how you try to transfer data, we haven't seen your code, and we haven't seen the compiler's error messages. (For more examples of how not to write help requests, see [Section 3.2 of this document](http://faculty.washington.edu/dchinn/how-not-to-code.pdf).) We could poke in the dark, but it would probably be more productive if you gave us a bit more detail explaining what doesn't work: show us the code you implemented, show us the compiler's error message, or be specific in some other way in describing what the problem is!
+
+## I'm not sure the mailing list is the right place to ask ...
+
+Yes, it probably is. Please direct your questions to the mailing list and not to individual developers. There are many reasons:
+
+  1. Others might have similar questions in the future and can search the archives.
+  1. There are many active users on the mailing list that are happy to help. There probably is someone who did something very similar before.
+  1. Imagine everyone would stop using the mailing list and email us directly. We would spend most of our time answering the same questions over and over.
+  1. Many users are reading the mailing list and are interested in deal.II in general and are learning by skimming emails. Give them a chance.
+  1. As a consequence of all this, we typically prioritize questions on mailing lists over emails sent directly to us asking for help.
+  1. Don't be afraid. There are no stupid questions (only off-topic ones). Everyone started out at some point. Asking the questions in the open helps us improve the library and documentation.
+
+That said, if there is something you can not discuss in the open, feel free to contact us!
+
+
+## How fast is deal.II?
+
+The answer to this question really depends on your metric. If you had to write, say, a Stokes solver with a particular linear solver, a particular time stepping scheme, on a piecewise polygonal domain, and Q2/Q1 elements, you can write a code that is 20% or 30% faster than what you would get when using deal.II because you know the building blocks, shape functions, mappings, etc. But it'll take you 6 months to do so, and 20,000 lines of code. On the other hand, when using deal.II, you can do it in 2 weeks and 204 lines (that's the number of semicolons in step-22).
+
+In other words, if by "fast" you mean the absolute maximal efficiency in terms of CPU time deal.II is more than likely to lose against a hand-written Fortran77 code. But for most of us, the real question of "fast" also includes the time it takes to get the code running and verified, and in that case deal.II is most likely the fastest library out there simply by virtue of the fact that it is by far the largest and most comprehensive finite element library available as Open Source.
+
+This all, by the way, does not mean that we don't care about speed: We spend a lot of effort profiling the library and working on the hot spots to make codes fast. The discussion of this issue in the introduction of step-22 is a good example. There are also some guidelines below on how to profile your code in the debugging section of this FAQ.
+
+## deal.II programs behave differently in 1d than in 2/3d
+
+In deal.II, you can write programs that look exactly the same in 2d and 3d, but there are cases where 1d is slightly different. That said, this is an area that we have significantly rewritten, and starting with deal.II 7.1, most cases should work in 1d in just the same way as they do in 2d/3d. If you find something that doesn't work, please report it to the mailing list.
+
+Historically, the differences primarily resulted from the fact that in deal.II, we represent vertices differently from lines and quads; whereas the latter can store information (for example boundary indicators, user flags, etc) vertices don't. As a consequence, the boundary indicator of a boundary part in 1d (i.e. either the left or right vertex) were determined by convention, rather than by setting it explicitly: the left boundary of a 1d domain always had boundary indicator zero, the right boundary always boundary indicator one. This was different from the 2d/3d case where by default (unless you explicitly set things differently) all boundaries have indicator zero. This left-boundary-has-id-0, right-boundary-has-id-1 is still the default today, but at least you can set the boundary indicators of these end-points to something different today.
+
+A second difference is that vertices have no extent, and so you can't apply quadrature to them. As a consequence, the FEFaceValues class wasn't usable in 1d. Again, this should work these days: every quadrature formula that has a single quadrature point is a valid one for points as well.
+
+## I want to use deal.II for work in my company. Do I need a special license?
+
+Before going into any more details, you **need** to carefully read the
+license deal.II is under. In particular, the explanations below are not meant
+to be legal advice and does not override the provisions in the Open Source
+license.
+
+However, before this, let us provide our overarching philosophy: It is our intention to have constructive relationships with those who want to use our work commercially, and we encourage commercial use. After having used a more restrictive license until 2013, we have come to the conclusion that these licenses serve neither side particularly well: it made commercial use difficult, and the lack of commercial use deprived us of critical feedback, potential contributions from professional users, and our users of potential employment opportunities. Everyone is better off with the LGPL license we are using now, and we hope that deal.II also finds use in commercial settings.
+
+Now for the smaller print: Generally, the LGPL is a fairly liberal license. In particular, if you *develop a code based on deal.II*, then there is no requirement that you also open source your own code: you can keep it closed source, under a proprietary license, and you need to give it to anyone (neither your customers nor to us).
+
+The LGPL is only restrictive in that the *changes you make to deal.II itself* must also be licensed under the LGPL. There is not frequently a need to change the library itself, and in many of these cases you will probably be interested to get them into the upstream development sources anyway (e.g., in cases of bugs) rather than having to forward port them indefinitely. Of course, we are interested in this as well. However, there is no such requirement that you upstream these changes: the only people you have to make these modifications to deal.II available to are your customers.
+
+As mentioned above, the preceding paragraphs are not a legal interpretation. For definite interpretations of the LGPL, you may want to consult lawyers familiar with the topic or search the web for more detailed interpretations.
+
+
+# Supported System Architectures
+
+## Can I use deal.II on a Windows platform?
+
+deal.II has been developed with a Unix-like environment in mind and it
+shows in a number of places regarding the build system and compilers
+supported. That said, there are multiple methods to get deal.II
+running if you have a Windows machine.
+
+### Run deal.II through a virtual box
+
+The simplest way to try out deal.II is to run it in a premade virtual machine. You can download the virtual machine for VirtualBox from http://www.math.clemson.edu/~heister/dealvm/
+and run it inside windows.
+
+Note that your experience depends on how powerful your machine is. More than 4GB RAM are recommended. A native installation of Linux is preferable (see below).
+
+### Dual-boot your machine with Ubuntu
+
+The simplest way to install Linux as a Windows user is to dual-boot. Dual-boot means that you simply install a second
+operating system on your computer and you choose which one to start
+when you boot the machine. Most versions of Linux support installing
+themselves as a second operating system. One example is using the Ubuntu installer for Windows. This installer will automatically dual-boot your system for you in a safe and fully reversible manner. Simply follow the instructions on
+http://www.ubuntu.com/download/desktop/install-ubuntu-with-windows
+
+If at some point in the future you wish to remove Ubuntu from your system, from the Windows program manager (add-remove programs in older versions and programs and features in newer versions) you can simply uninstall Ubuntu as you would any other program.
+
+*Note:* The actual install file is linked through the text "Windows installer" in the first gray box.  You will be prompted to donate to Ubuntu, which is entirely optional. You will also be prompted to use a different version of Ubuntu if you use Windows 8.
+
+
+### Run deal.II natively on Windows
+
+Native Windows support for deal.II is currently experimental and not officially supported.
+
+In principle, it is able to compile and use deal.II within the CygWin environment as well as on native Windows with the MinGW or MinGW-w64 compiler.
+See the separate page on [for more details.
+
+
+### Are any of the native Windows compilers supported by deal.II?
+
+If you are thinking of compilers like Microsoft Visual C++ or Borland C++, then the answer is: No, not at the moment.
+The basic problem is that none of the main developers use Windows and
+as in any other volunteer project, things happen if people with the
+necessary expertise step forward to make it work.
+
+The longer answer is that e.g. the primary Windows compiler, Visual Studio C++, violates some language standards in areas that are heavily used in deal.II. To fix this without breaking support for gcc, clang and icc is a significant amount of work, which requires people to do it. If you are familiar with C++ and would like to help out our project, then any work in this direction, even if only incremental would certainly be welcome.
+
+On the positive side, the configuration of deal.II uses `cmake` which
+runs just fine natively on Windows and can produce Visual Studio
+project files that allow you to import all of the build instructions
+automatically.
+
+
+## Can I use deal.II on an Apple Macintosh?
+
+Yes, at least on the more modern OS X operating systems this works just fine. deal.II supports native compilers shipping with XCode as well as gcc from Mac Ports.
+
+The only issue we are currently aware of is that if deal.II is configured to interface with PETSc, then PETSc needs to be configured with the --with-x=0 flag to prevent linking in the X11 libraries (you probably won't need them anyway). Installing with PETSc has a myriad of other problems, though we believe that we have a way to stably interface it. You may want to read through the PETSc-related entries further down, however.
+
+## Does deal.II support shared memory parallel computing?
+
+Yes. deal.II supports multithreading with the help of the [http://www.threadingbuildingblocks.org Threading Building Blocks (TBB) library](c967ec2ff74d85bd4327f9f773a93af3]). It is enabled by default and can be controlled via the `DEAL_II_WITH_THREADS` configuration toggle passed to `cmake` (see the deal.II readme file).
+
+## Does deal.II support parallel computing with message passing?
+
+Yes, and in fact it has been shown to scale very nicely to at least 16,384 processor cores in a paper by Bangerth, Burstedde, Heister and Kronbichler. You should take a look at the documentation modules discussing parallel computing, as well as the step-40 tutorial program.
+
+
+## How does deal.II support multi-threading?
+
+deal.II will use multi-threading using several approaches:
+1. some BLAS routines might be multi-threaded (typically using OpenMP). This can be controlled from the command line using OMP_NUM_THREADS (also see the entry in the FAQ below)
+2. Many places in the library are parallelized using the Threading Building Blocks (TBB) library.
+
+MPI_InitFinalize() has an optional third argument that specifies the
+number of threads to use for the TBB. The default is 1. This gets send to the TBB via a call to  MultithreadInfo::set_thread_limit(). If you pass numbers::invalid_unsigned_int into MPI_InitFinalize (or if you don't use that class, call set_thread_limit directly) then TBB will use the maximum number of threads that makes sense (and you can limit it using DEAL_II_NUM_THREADS from the command line).
+
+Also note that while our Trilinos wrappers support multi-threading, the PETSc wrappers do not support this at this time, so you need to run with one thread per process.
+
+## My deal.II installation links with the Threading Building Blocks (TBB) but doesn't appear to use multiple threads!
+
+This may be a quirky interaction with the [GOTO BLAS](http://www.tacc.utexas.edu/tacc-projects/gotoblas2/) :-( If you use Trilinos or PETSc, both of these require a BLAS library from your system, and the deal.II cmake configuration will make sure that it is linked with. The problem stems from the fact that by default, the GOTO BLAS will simply grab all cores of the system for its own use, and -- before your `main()` function even starts, allow the main thread to use only a single core. (For the technically interested: it sets the processor scheduling affinity mask, using `set_sched_affinity` to a single bit.)
+
+When the TBB initialization runs, still before `main()` starts, it will find that it can only run on a single core and will consequently not be able to work on multiple tasks in parallel.
+
+The solution to this problem is to forbit the GOTO BLAS to grab all processors for itself, since we spend very little time in BLAS anyway. This can be done by setting either the `OMP_NUM_THREADS` or `GOTO_NUM_THREADS` environment variables to 1, see http://www.tacc.utexas.edu/tacc-software/gotoblas2/faq .
+
+
+# Configuration and Compiling
+
+## Where do I start?
+
+Have a look at the  [ReadMe instructions](http://www.dealii.org/developer/readme.html) for details on how to configure and install the library with `cmake`.
+
+## I tried to install deal.II on system X and it does not work
+
+That does occasionally (though relatively rarely) happen, in particular if you work on an operating system or with a compiler that the primary developers don't have access to. In a case like this, you should ask for help on the mailing list. However, remember: If your question only contains the text "I tried to install deal.II on system X and it does not work" then that's not quite enough to figure out what is happening. Even though the people developing this software belong to the most able programmers in the universe (and a decent number of parallel universes), all of us need data to find errors. So, whatever went wrong, paste the error message into your email. If the error is from the `cmake` invocation, show us the error message that was printed on screen.
+If the error happens after configuring and during compiling, add lines from screen output showing the error to the mail.
+
+
+## How do I change the compiler?
+
+deal.II can be compiled by a number of compilers without problems (see the section [prerequisites](http://www.dealii.org/readme.html#prerequisites) in the readme file). If `cmake` does not pick the right one, selecting another is simple, and described in a [section](http://www.dealii.org/developer/development/cmake.html#compiler) in the [cmake documentation](http://www.dealii.org/developer/development/cmake.html).
+
+
+## I get warnings during linking when compiling the library. What's wrong?
+
+On some linux distributions with particular versions of the system compiler, one can get warnings like these during the linking stage of compiling the library:
+```
+`.L3019' referenced in section `.rodata' of
+/home/bangerth/deal.II/lib/lac/sparse_matrix.float.g.o: defined in discarded section
+`.gnu.linkonce.t._ZN15SparsityPattern21optimized_lower_boundEPKjS1_RS0_'
+of /home/bangerth/deal.II/lib/lac/sparse_matrix.float.g.o
+```
+
+While annoying, these warnings do not actually seem to indicate anything particularly harmful. Apparently, the compiler generates the same code multiple times in exactly the same form, and the linker is only warning that it is throwing away all but one of the copies. There doesn't seem to be way to avoid these warnings, but they can be safely ignored.
+
+## I can't seem to link/run with PETSc
+
+Recent deal.II releases support PETSc 3.0 and later. This works, but there are a number of things that can go wrong and that result in compilation or linker errors, as explained below. If your program links properly with PETSc support, it will very likely also produce the correct results.
+
+If you get errors like this when trying to run step-17 of the tutorials, even though linking seems to have succeeded just fine:
+```
+   [make run
+   ============================ Running step-17
+   ./step-17: error while loading shared libraries: libpetsc.so: cannot open
+              shared object file: No such file or directory
+   make: *** [run](step-17]) Error 127
+```
+
+this means is that while linking, the compiler could find the libpetsc.so library, but the executable can't find it when running. The reason is that we can tell the linker where
+to look, but the executable apparently did not remember this (this is the standard Unix behavior). What you
+have to do is to set the LD_LIBRARY_PATH to include the path to the PETSc libraries. For
+example, under `bash` you would have to do this:
+```
+   export LD_LIBRARY_PATH=/path/to/petsc/libraries:$LD_LIBRARY_PATH
+```
+
+If you do so, the Unix loader can query the environment variable for where to find this particular library when trying to run the executable, and running the program should succeed.
+
+Similarly, if you get errors of the kind during linking
+```
+/home/xxx/deal.II/lib/libdeal_II.g.so: undefined reference to
+`KSPSetInitialGuessNonzero(_p_KSP*, PetscTruth)'
+/home/xxx/deal.II/lib/libdeal_II.g.so: undefined reference to
+`VecAXPY(_p_Vec*, double, _p_Vec*)'
+...
+```
+
+then the compiler can't seem to find the PETSc libraries. The solution is as above: specify the path to those libraries via `LD_LIBRARY_PATH`.
+
+
+### Is there a sure-fire way to compile deal.II with PETSc?
+
+Short answer is "No". The slightly longer answer is, "PETSc has too many knobs, switches, dials, and a kitchen sink too many for its own damned good. There is not a sure-fire way to compile deal.II with PETSc!". It turns out that PETSc is a very versatile machine and, as such, there is no shortage of things that can go wrong in trying to configure PETSc to work seamlessly with deal.II on a first attempt. We have all struggled with this, although it has become a lot better in recent years.
+
+You can find instructions on how to install PETSc linked to from the deal.II ReadMe file, or going directly to http://www.dealii.org/developer/external-libs/petsc.html .
+
+### I want to use HYPRE through PETSc
+
+Hypre implements algebraic multigrid methods (AMG) as preconditioners, for example the BoomerAMG method. AMGs are among the most efficient preconditioners available and they have also been shown to be scalable to thousands of processors. deal.II allows the use of Hypre through the PETScWrappers::PreconditionBoomerAMG class; it is used in `step-40`. Hypre can be installed as a sub-package of PETSc and deal.II can access it through the PETSc interfaces.
+
+To use the Hypre interfaces through PETSc, you need to configure PETSc as discussed in http://www.dealii.org/developer/external-libs/petsc.html  , and add the following switch to the command line: `--download-hypre=1`.
+
+### Is there a sure-fire way to compile dealii with SLEPc?
+
+Happily, the answer to this question is a definite yes; that is, <b>if you have successfully compiled and linked PETSc already</b>.
+
+The real trick here is that during configuration SLEPc will pull out PETSc's configuration and just does whatever that tells it to do. Detailed steps are discussed in http://www.dealii.org/developer/external-libs/slepc.html .
+
+Once deal.II is compiled, it is worth to start by looking at the step-36 tutorial program to see how to get started using the interface with SLEPc.
+
+<i>
+Note: To use the solvers and other algorithms SLEPc provides it is absolutely essential to have your PETSc installation working correctly since they share the same vector-matrix (and other) data structures.
+</i>
+
+
+## Trilinos detection fails with an error in the file `Sacado.hpp` or `Sacado_cmath.hpp`
+
+This is a complicated one (and it should also be fixed in more recent Trilinos versions). In the Trilinos file `Sacado_cmath.hpp`, there is some code of the form
+```
+  namespace std {
+    inline float acosh(float x) {
+      return std::log(x + std::sqrt(x*x - float(1.0))); }
+    ...
+  }
+```
+
+In other words, Sacado is putting things into namespace `std`. The functions it is putting there are functions that have been defined by the C99 standard but that didn't make it into the C++98 standard before; some of them are widely used. The problem is that these functions were later added to the C++0x (now C++11) standard and so if your compiler is new enough (e.g. GCC 4.5 and later) then the compiler's C++ standard library already contains these functions. Adding them again in this file then yields errors of the kind
+```
+/home/.../trilinos-10.4.2/include/Sacado_cmath.hpp: In function 'float std::acosh(float)':
+/home/.../trilinos-10.4.2/include/Sacado_cmath.hpp:41:16: error: redefinition of 'float std::acosh(float)'
+/usr/include/c++/4.5/tr1_impl/cmath:321:3: error: 'float std::acosh(float)' previously defined here
+```
+
+The only useful way to avoid this error is to edit the Trilinos header file. To do this, find and open the file `include/Sacado_cmath.hpp` in the directory in which Trilinos was installed. Then change the block enclosed in
+```
+  namespace std {
+    ...
+  }
+```
+
+to read
+```
+#ifndef _GLIBCXX_USE_C99_MATH
+  namespace std {
+    ...
+  }
+#endif
+```
+
+What this will do is make sure that the new members of namespace `std` are only added if the compiler has not already done so itself.
+
+
+
+
+## My program links with some template parameters but not with others.
+
+deall.II has many types for whose initialization you need to provide a template parameter, e.g. `SparseMatrix<double>`. The implementation of these classes can typically be found in files ending `.templates.h`, e.g. `sparse_matrix.templates.h`. The corresponding `.cc` files, e.g. `sparse_matrix.cc`, essentially only provide the explicit instantiations of these classes for the most commonly used template parameters. Sometimes this is done by including a corresponding `.inst` file, e.g. `sparse_matrix.inst`.
+
+If you want to use a data type with a template parameter for which there is an explicit instantiation, you only need to include the respective `.h` header file, e.g. `sparse_matrix.h`. If, however, you want to use a template parameter for which there is no explicit instantiation in the corresponding `.cc` file, you have to include the respective `.templates.h` file in order for your program to link successfully.
+
+The reason for all of this is essentially a matter of reducing compilation time. As long as you use data types with template parameters for which there is an explicit instantiation - and this should be the case most of the time - you do not need to compile the respective (lengthy) .templates.h file every time you compile your code. If, however, you need to use an instance of e.g. `SparseMatrix<bool>`, you have to include the respective `.templates.h` file and you have to compile it along with the remaining files of your program every time.
+
+## When trying to run my program on Mac OS X, I get an error of the kind `dyld: Library not loaded: libdeal_II.g.7.0.0.dylib. Reason: image not found`
+
+This goes hand in hand with the following message you should have gotten at the end of the output of `./configure`:
+
+```
+     Please add the line
+        export DYLD_LIBRARY_PATH=\$DYLD_LIBRARY_PATH:$DEAL2_DIR/lib
+     to your .bash_profile file so that OSX will be
+     able to find the deal.II shared libraries when
+     executing your programs.
+```
+
+What happens is this: when you say "make all", all the deal.II files are
+compiled and linked into a library (called libdeal_II.g.7.0.0) which on Macs
+have the file ending .dylib. Then you go to examples/step-1 and compile your
+program, which uses all the functions and classes that have previously been
+put into this library.
+
+Now the following happens: On most operating systems, the actual executable
+program (i.e. the file step-1 in your directory that resulted from compiling)
+does not contain any information that would indicate where the various
+libraries that it uses can be found. For example, the step-1 program does not
+know where the libdeal_II.g.7.0.0.dylib file is. This is just how most
+operating systems function. But when you want to execute the program, somehow
+the program has to know where the library it needs is located. On most
+unix-like operating systems, this is done by setting an "environment
+variable" -- on linux this would the variable "LD_LIBRARY_PATH", on Mac OS X
+it is "DYLD_LIBRARY_PATH".
+
+So to let the operating system know where the library is located, you could
+type
+  export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:/Users/renjun/deal.ii/lib
+every time before you want to execute the program. That would be cumbersome. A
+simpler way would be if this export command is executed every time when you
+open a new shell window. This can be achieved by putting this command in a
+file that is executed every time you open a shell window. Depending on what
+shell you use, these files are alternatively called
+  .cshrc
+  .bashrc
+  .bash_profile
+or similar. I'm not quite sure which file is relevant for you, but you can try
+them one after the other by putting the text in there, closing the window,
+opening it again, and then trying to execute
+  ./step-1
+(or saying "make run" in this directory) and seeing whether that works.
+
+# C++ questions
+
+## What integrated development environment (IDE) works well with deal.II?
+
+The short answer is probably: whatever works best for you. deal.II uses standard unix-style Makefiles, which most IDEs should support. In the past, many of the main developers have used emacs (or even vi), but there are much better tools around today, such as [eclipse](http://www.eclipse.org/), [KDevelop](http://www.kdevelop.org), [Xcode](http://developer.apple.com/technologies/tools/), [QtCreator](http://qt.nokia.com/products/developer-tools/), all of which have been used by people using deal.II.
+
+We have gathered some notes on using the following IDEs for deal.II:
+  - [[Eclipse]]
+  - [- [emacs](KDevelop]): While we don't recommend using emacs any more, this link provides a couple of notes on formatting styles used within deal.II.
+
+When thinking about what IDE to use, keep this in mind: Many of us have used emacs (or, worse, vi) for years and feel very comfortable with it. But, emacs and vi were both started in 1976, at a time when computers had little memory, virtually no CPU power, and only text-based interfaces. While they have of course become a lot better over time, the design limitations this involved are still very much part of the code base: fundamentally, they are both still text-based and file-oriented. What IDEs can provide are multiple views of the same project in graphical and textual form and, more importantly, can integrate entire projects spanning hundreds of files in multiple directories: they know where a variable is declared (even if it's in a different file), what it's type is, and the properties of this type. Neither emacs nor vi nor any other older editor can provide anything that comes even close to what kdevelop or eclipse can offer in this regard.
+
+What all this implies is that you should consider using one of the more modern tools, even if you're well acquainted with an existing, older one. Of course it takes a while to get used to a new application but my (Wolfgang's) experience with switching from emacs to kdevelop was that I have become '''so''' much more productive by using modern tools that the time invested in learning it was amortized very quickly. I found this experience a real eye-opener!
+
+## Is there a good introduction to C++?
+
+There are of course many good books and online resources that explain C++. As far as websites are concerned, [www.cplusplus.com](http://www.cplusplus.com) has both [reference material for individual classes of the C++ standard library](http://cplusplus.com/reference/) as well as a [a tutorial on parts of the C++ language](http://cplusplus.com/tutorial) if you want to brush up on the correct syntax of things.
+
+## Are there features of C++ that you avoid in deal.II?
+
+There are few things that we avoid <i>as a matter of principle.</i> C++ is, by and large, a pretty well designed language in the sense that its features are there because they have been found to be useful by a lot of people. As an example, people have found that it is easier to write and debug code that throws exceptions in error cases rather than encoding error situations by special return values (e.g. by returning -1). There are of course ways to avoid exceptions (or templates, or certain parts of the C++ standard libraries, or any number of other things people have found objectionable in C++) and some software projects have chosen to restrict the use of C++ (for example Mozilla) or to emulate only those parts of C++ they like in C (e.g. the GNOME desktop environment, which leads to awkward to understand code [as described here](http://developer.gnome.org/gobject/stable/howto-gobject-methods.html)).
+
+But ultimately, it is our belief that these approaches shoot their inventors in the foot: they avoid features of C++ that were really intended to make programming life simpler. It may be simpler for novice programmers to read code without templates; ultimately, however, learning to read and use templates will make you a much more productive programmer since you don't write the same code multiple times. As a consequence, the use of C++ is driven by the question of what is best suited to write a particular algorithm, not by abstract considerations. This fits into the realization that deal.II is a large piece of software -- not a small research project -- that requires professional software management practices and for which long term development can no longer be driven by an individual programmer's preferences of style.
+
+## Why use templates for the space dimension?
+
+The fundamental motivation for this is to use dimension-independent programming, i.e. you want to write code in such a way that it looks exactly the same in 2d as in 3d (or 1d, for that matter). There are of course many ways to do this (and libraries have done this for a long time before deal.II has). The three most popular ones are to use a preprocessor #define that sets the space dimension globally, to use a global variable that does this, and to have each object have a member variable that denotes the space dimension it is supposed to live in (in much the same way as the template argument does in deal.II). Neither of these approaches is optimal (nor is our own approach to use templates), however. In particular, using a preprocessor symbol or a global variable will not allow you to mix and match objects of different dimensionality. There are situations when you want to do that; for example deal.II internally builds higher dimensional quadrature formulas as tensor products of lower dimensional ones, and in application codes you may wish to discretize both volume models (e.g. simulating 3d models of plate tectonics and mountain belt formation) with surface models (e.g. erosion processes on the 2d earth surface).
+
+This leaves the option to have a member variable denoting the space dimension in each object, a choice most other finite element libraries have followed. But this isn't optimal either, for two reasons. For example, consider this code that describes the equivalent of the `Point<dim>` class for points in dim-dimensional space and its `norm()` member function:
+
+```
+  class Point {
+    public:
+      Point (const unsigned int dimension)
+                   : dim(dimension),
+                     coordinates (new double[{}
+
+      ~Point() { delete[](dim])) coordinates; }
+
+      double norm () const;
+      ...
+    private:
+      unsigned int dim;
+      double **coordinates;
+  };
+
+  double Point::norm () const {
+    double s = 0;
+    for (unsigned int d=0; d<dim; ++d)
+      s **= coordinates[* coordinates[d](d]);
+    return std::sqrt(s);
+  }
+```
+
+This is going to lead to rather slow code, for multiple reasons:
+
+ - The constructor and destructor have to allocate and deallocate memory on the heap, both expensive processes.
+
+ - When accessing any element of the `coordinates` array, two pointers have to be dereferenced. For example, the access to `coordinates[really expands to `(*((*this).coordinates + d)`.
+
+ - The compiler can not optimize the loop since the upper bound `dim` of the loop variable is unknown at compile time.
+
+
+Compare this to the way deal.II implements this class:
+
+```
+  template <unsigned int dim>
+  class Point {
+    public:
+      Point () {}
+      ~Point() {}
+
+      double norm () const;
+      ...
+    private:
+      double coordinates[dim](d]`);
+  };
+
+  template <unsigned int dim>
+  double Point<dim>::norm () const {
+    double s = 0;
+    for (unsigned int d=0; d<dim; ++d)
+      s **= coordinates[* coordinates[d](d]);
+    return std::sqrt(s);
+  }
+```
+
+Here, the following holds:
+
+ - Constructor and destructor do not have to allocate and deallocate memory on the heap; rather, since the size of the `coordinates` array is known at compile time (i.e. whenever you instantiate the template for a particular dimension), the array lives on the stack. It is also much smaller than before: the dimension is encoded in the type and doesn't need a memory location, we don't need to store a pointer to an array, and we don't incur the memory overhead of having to manage an object on the heap.
+
+ - When accessing any element of the `coordinates` array, only one pointer has to be dereferenced. For example, the access to `coordinates[really expands to `(*(this + d)`.
+
+ - The compiler can optimize the loop since the upper bound `dim` of the loop variable is known at compile time. In particular, for a point in 2d, the code the compiler will produce is likely to look more like this because the loop can be unrolled and the loop counter can be optimized away:
+```
+  double Point<2>::norm () const {
+    return std::sqrt(s)(coordinates[0](d]`) ** coordinates[+ coordinates[1](0]) ** coordinates[}
+```
+Obviously, for a 3d point, the code will look differently, but the compiler can do this since it knows what the dimension of the point is at compile time.
+
+There is another reason for the deal.II way: type safety. In short, a 2d point is not the same as a 3d point. If you assign one to the other, then this may be on purpose and the executable should simply change the value of the `dim` member variable from 2 to 3. But it may also be a legitimate error -- for example, you shouldn't be able to use 2d points to initialize the 3d quadrature points needed to integrate on a 3d cell. This can of course be caught by run-time checks, but the reason for strongly typed languages such as C++ has always been that it is much more efficient if the compiler can already catch this sort of error at compile time. Using templates for the space dimension avoids these sort of mistakes up front by forcing the programmer to explicitly specify her intent, rather than encoding intent in assertions.
+
+Of course there are also downsides to using templates. Most notably, error messages that involve templates are notoriously unreadable, and that compiling template heavy code is slow: for example, we have to compile the `Point` class three times (for dim=1, dim=2 and dim=3) rather than only once. Nevertheless, we believe that these valid objections do not outweigh the benefits of templates.
+
+## Doesn't it take forever to compile templates?
+
+Yes, in general it does. The reason is that while for non-templates it is enough to put the ''declaration'' of a function into the header file and the ''definition'' into the `.cc` file, for templates that doesn't work. Let's say you have something like
+```
+  template <typename T> T square (const T & t);
+```
+
+in your header file and you put the definition
+```
+  template <typename T> T square (const T & t) { return t*t; }
+```
+
+into the `.cc` file, then the compiler will say "Yes, I saw this template, and if I see a use of this function later on I will generate a function from it by replacing `T` by whatever type you use in the call". But if there is no call later on in the same `.cc` file, then the compiler won't do anything. If, at the same time, in a different `.cc` file that includes the header file, you use the function with `T=double` the compiler will say "Yes, I saw the declaration, but there is no definition; I assume the function has been compiled in a different `.cc` file with `T=double` and I'll simply record a call to this instantiation in the object file". The call will then be resolved at link time if indeed another object file contains an instantiation of the template for `T=double`. However, if no other object file contains such a definition, a linker error will result.
+
+In general, for functions like the above, it is difficult to foresee what kinds of template arguments the function may be instantiated for, and so there is no real practical way to put the definition into a `.cc` file. Rather, one puts it into a header file, and so all `.cc` files that may use this function see its definition (i.e. its body) and the compiler can instantiate it in each source file for whatever template argument is necessary. This makes sure that you never get linker errors, but at the same time it makes compiling slow since every header file now not only has to parse the function's declaration, but also its definition -- and in the case of deal.II the definitions of all template functions add up to tens or hundreds of thousands of lines of code. This is one of the reason why many C++ programs compile relatively slowly: because they use a significant part of the C++ standard library, most of which consists of templates.
+
+deal.II can avoid much of this overhead. The trick is to recognize that in the example above we don't really know what types `T` user code may possibly want to use for this template. But in the case of using the space dimension as a template parameter, we know pretty exactly all the possibly values: `Triangulation<dim>` may really only be instantiated for `dim=1, 2, 3` and for nothing else. Consequently, we can do the following: Put all the definitions of the member functions of deal.II into the `.cc` file and at the bottom of the file instruct the compiler to please instantiate all of these templates for `dim=1, 2, 3`. Similar things can be done for many other template functions in deal.II; for example, there are a good number of functions that require vector types as template arguments, of which deal.II provides a good number, yet this list is finite and enumerable. Consequently, we can simply, at the bottom of the `.cc` file, tell the compiler to instantiate all of these template functions for every single vector type deal.II supports, and then don't have to put thousands of lines of template definitions into header files.
+
+In many cases, enumerating all possible template arguments is tedious; it is also difficult to extend this list when a new vector type is added, for example. To simplify this task, deal.II uses a preprocessor: for many files that want to instantiate a function or class for multiple template arguments, we have a file `.inst.in` that has the equivalent of a `for`-loop over all possible values or types for a template argument; the file is processed by the `common/scripts/expand_instantiations` program to produce a `.inst` file that can then be included into the `.cc` file.
+
+## Why do I need to use `typename` in all these templates?
+
+This is indeed a frequent question. To answer it, it is necessary to understand how a compiler deals with templates, which will take a bit of space here. Let's take for example this case:
+
+```
+  void f(int);
+  void g(double d) {
+    f(d);
+  }
+  void f(double);
+```
+
+Here, in the function `void g(double)`, we call `f` with a double as an argument. Because at that point the compiler has only seen the declaration of the first overload of `f`, it will convert the double `d` to an integer and call this first overload. The fact that a second overload was declared later does not change this situation, since it wasn't visible at the time the compiler parsed `g`.
+
+Templates are designed to work essentially the same, but there are slight complications. Take this example:
+
+```
+  void f(int);
+  void f(char);
+  template <typename T> void g(T t) {
+    f(1.1);
+    f(t);
+  }
+  void f(double);
+```
+
+In the first line of `g`, the same thing happens as before: the argument is cast to `int` and the
+first of the two overloads of `f` is called.
+But when the compiler sees the template, it doesn't know yet what type
+`T` actually represents, so there is no way to settle on one of the two functions `f` the compiler has seen before when deciding about the second line. In fact, the C++ standard says that because the type of the argument `t` in the call depends on the template type, determining what function to actually call should only happen <i>at the time and place when the template is instantiated</i> (this is called <i>argument dependent name lookup</i> or <i>ADL</i>). In other words, if below the code above we had this:
+```
+  void h() {
+     g(1.1);
+  }
+```
+
+then in the instantiation of `g` the first call would be to `f(int)` (because the argument 1.1 does not depend on the type given in the template argument, and consequently only functions are considered that were seen <i>before the definition of</i> `g(T)`) whereas the second call to `f` would be to `f(double)` -- even though `f(double)` wasn't even declared at the place the compiler saw the call in the template (though it is available at the place where we instantiate `g<double>`) -- because the function call argument `t` has type `T` and therefore depends on the template argument.
+
+Argument dependent lookup allows you to use function templates like `g` with your own data types. For example, you could have your own library that does
+```
+  #include <f.h>
+
+  struct X { /* something */ };
+
+  void f (const X & x) { /* do something with the X */ }
+
+  void my_function() {
+    X x;
+    g(x);
+  }
+```
+
+Presumably the writer of the `g` function did not know about your own type `X` yet, but her code still works because you provided a suitable overload of `f` in your own code.
+
+So ADL is clever and allows you to use templates in ways the author of the template did not anticipate. But it has a dark side: for every statement in your code, the compiler has to figure out whether it depends on the template types or not, and it needs in fact to know quite a lot about it. Take this example:
+
+```
+  int p;
+  template <typename T> void g(T t) {
+    T::something * p;
+    f(p);
+  }
+```
+
+Here, is the call to `f` dependent because `p` depends on the type `T`? If `f` is called with an argument of type `X` that is declared like this
+
+```
+  struct X {
+    typedef int something;
+  };
+```
+
+then `T::something * p;` would declare a local variable called `p` that is of type pointer-to-int. On the other hand, if we had
+
+```
+  struct X {
+    static double something;
+  };
+```
+
+then `T::something * p;` multiplies the variable `X::something` by the global variable `p` and ignores the result of the multiplication. The following call to `f` would then be non-dependent because the type of the (global) variable `p` does not depend on the template argument.
+
+The example shows that the compiler can't know whether a call is dependent or not in a template it is just seeing unless we tell it that `T::something` is supposed to be a type or a variable or function name. To avoid this situation, C++ says: if a compiler sees `T::something` then this is a variable or function name unless it is prefixed by the keyword `typename` in which case it is supposed to be a type. In other words, the call to `f` here is going to be non-dependent:
+```
+  int p;
+  template <typename T> void g(T t) {
+    T::something * p;
+    f(p);
+  }
+```
+
+and instantiating `g` with the first example for `X` is going to lead to errors because `T::something` didn't turn out to be a variable. On the other hand, if we had
+```
+  int p;
+  template <typename T> void g(T t) {
+    typename T::something * p;
+    f(p);
+  }
+```
+
+then the call is dependent and will be deferred until the compiler knows the type of `T`.
+
+## Why do I need to use `this->` in all these templates?
+
+This is a consequence of the same rule in the C++ standard as discussed in the previous question, Argument Dependent Lookup of names (ADL). Consider this piece of code:
+```
+  template <typename T> class Base {
+    public:
+      void f();
+  };
+
+  template <typename T> class Derived : public Base<T> {
+    public:
+      void g();
+  };
+
+  template <typename T> void Derived<T>::g() {
+    f();
+  }
+```
+
+By the rules, when the compiler <i>parses</i> the function `Derived::g` (note that parsing happens before and independently of <i>instantiating</i> the function for a particular argument type `T`), it sees that the call to `f()` does not depend on the template type and so it looks for a declaration of such a function somewhere. In the example above, it doesn't find one (we'll come to this in a second), which will yield an error. On the other hand, in this code,
+```
+  void f(); // global function
+
+  template <typename T> class Base {
+    public:
+      void f();
+  };
+
+  template <typename T> class Derived : public Base<T> {
+    public:
+      void g();
+  };
+
+  template <typename T> void Derived<T>::g() {
+    f();
+  }
+```
+
+it would find the global function and so when instantiating the function for, say, `T=int`, you'd get a function `Derived<int>::g` that would call the global function `::f`. This may or may not be what you had in mind.
+
+The question of course is why the compiler didn't record a call to `Base<T>::f` in `Derived<int>::g`? After all, the compiler knows that `Derived` is derived from `Base`. This has a lot to do with the fact that at the time of <i>parsing</i> the template, the compiler doesn't know for which template arguments the template will later be instantiated, and with explicit or partial specializations.  Consider for example this code:
+```
+  template <typename T> class Base {
+    public:
+      void f();
+  };
+
+  class X {
+    public:
+      void f();
+  };
+
+  template <> class Base<int> : public X {};
+
+  template <typename T> class Derived : public Base<T> {
+    public:
+      void g();
+  };
+
+  template <typename T> void Derived<T>::g() {
+    f();
+  }
+```
+
+Here, if you look at `Derived<T>::g`, the call to `f()` will be resolved to `Base<T>::f` for all possible types `T`, unless `T=int` in which case the call will be to `X::f`. The point is that at the time the compiler sees (parses) the template, it simply doesn't know yet what `T` is, and so ADL says: if the call is not dependent, find a non-dependent function to record (e.g. a global function) rather than trying to find a call in scopes you can't yet know will be relevant (e.g. `Base` or `X`). Likewise, in this code,
+```
+  template <typename T> class Base {
+    public:
+      void f();
+  };
+
+  template <> class Base<int> {
+    public:
+      struct f {};
+  };
+
+  template <typename T> class Derived : public Base<T> {
+    public:
+      void g();
+  };
+
+  template <typename T> void Derived<T>::g() {
+    f();
+  }
+```
+
+the meaning of `f()` changes depending on the template type: if `T=int`, it creates an object of type `Base<int>>::f` and then throws the object away again immediately. For all other template arguments `T`, it calls `Base::f`.
+
+Given this longish description of how compilers look up names under the ADL rule, let's get back to the original question: If you have this code,
+```
+  template <typename T> class Base {
+    public:
+      void f();
+  };
+
+  template <typename T> class Derived : public Base<T> {
+    public:
+      void g();
+  };
+
+  template <typename T> void Derived<T>::g() {
+    f();
+  }
+```
+
+how do you achieve that the call in `Derived::g` goes to `Base::f`? The answer is: Tell the compiler to defer the decision of what the call is supposed to do till the time when it knows what `T` actually is. And we've already seen how to do that: we need to make the call <i>dependent</i> on `T`! The way to do that is this:
+```
+  template <typename T> void Derived<T>::g() {
+    this->f();
+  }
+```
+
+Here, `this` is a pointer to an object of type `Derived<T>`, which is of course dependent. So the resolution of what the statement is supposed to represent is deferred until instantiation time; at that time, however, the compiler knows what the base class is (for example it knows if there are explicit specializations) and so it knows which base classes to look into in an attempt to find a function with the name `f`.
+
+## Does deal.II use features of C++2011 (formerly known as C++0x or C++1x)?
+
+We strive to keep deal.II compatible with the previous C++ standard, C++98, to make sure that deal.II can be built by all widely available compilers on current and recent operating systems. This typically prevents the use of new language features until some five years after compilers first implement them reliably.
+
+That said, deal.II does use some elements of C++2011 that have been added to the C++ standard library. Specifically, this includes the `std::shared_ptr, std::function, std::bind, std::array, std::tuple` and `std::thread` facilities. We can do that because we can fall back to the implementation of these features available through the BOOST library whenever a compiler does not provide them. To this end, deal.II has a namespace `dealii::std_cxx1x` into which we either import a name such as `std::shared_ptr` through a `using` statement if the compiler provides it, or otherwise import the name `boost::shared_ptr`. Since the BOOST classes have in almost all instances the exact same interface as the standard classes, the use of a name such as `std_cxx1x::shared_ptr` transparently provides the necessary functionality in deal.II and user codes.
+
+## Can I convert Triangulation cell iterators to DoFHandler cell iterators?
+
+Yes. You can also convert between iterators belonging to different DoFHandlers as long as the are based on the identical Triangulation:
+
+```
+Triangulation<2>::active_cell_iterator it = triangulation.begin_active();
+
+DoFHandler<2>::active_cell_iterator it2 (&triangulation, it->level(), it->index(), &dof_handler);
+```
+
+# Questions about specific behavior of parts of deal.II
+
+## How do I create the mesh for my problem?
+
+Before answering the immediate question, one remark: When you use adaptive mesh refinement, you definitely want the initial mesh to be as coarse as possible. The reason is that you can make it as fine as you want using adaptive refinement as long as you have memory and CPU time available. However, this requires that you don't waste mesh cells in parts of the domain where they don't pay off. As a consequence, you don't want to start with a mesh that is too fine to start with, because that takes up a good part of your cell budget already, and because you can't coarsen away cells that are in the initial mesh.
+
+That said, there are essentially three ways to generate a mesh, all of which are discussed in significantly more detail in the step-49 tutorial program:
+ - For many standard geometries (square, cube, circle, sphere, ...) there are functions in namespace `GridGenerator` that can generate coarse meshes.
+ - If `GridGenerator` does not offer a mesh for the geometry you have, but if the geometry is simple, then you can often create one "by hand". Take a look, for example, at how we create the mesh in step-14 using the `Triangulation::create_triangulation` function. All you need to do is take a piece of paper, draw the geometry and a number of coarse cells that form quadrilaterals, identify the locations of vertices and the connectivity from cells to vertices, and pass the corresponding lists to the Triangulation. Something similar can be done for simple 3d geometries.
+ - If your geometry is truly complicated enough so that you can't draw a mesh by hand any more (i.e. if it requires more than, for example, 20-30 coarse mesh cells), then you'll need a mesh generator. For quadrilaterals and hexahedra, there aren't all that many mesh generators. [http://geuz.org/gmsh/ gmsh](1]);), [lagrit](https://lagrit.lanl.gov/) and [cubit](http://cubit.sandia.gov/) come to mind. The primary problem is that most mesh generators' output meshes aren't particularly coarse by default, so you may want to pay particular attention to this point when running the mesh generator. (This is relevant since deal.II is particularly good about creating adaptively refined meshes, but if your coarse mesh is already very large then you will likely not have a lot of resources left to adaptively refine it some more.) Once you have a mesh from a mesh generator, you would read it using the `GridIn` class, as demonstrated, for example, in step-5.
+
+## How do I describe complex boundaries?
+
+You need to define classes derived from the `Boundary` base class and attach these to particular parts of the boundary of the triangulation. The `Triangulation` class will then query your boundary object whenever it needs a new point on the boundary after mesh refinement.
+
+In deal.II releases after 8.1, the way geometry is described has been made much more flexible. In particular, it is no longer only possible to describe the boundary, but it is also possible to describe where points in the interior lie. The step-53 tutorial program explains how this is done for a realistic example.
+
+
+## I am using discontinuous Lagrange elements (`FE_DGQ`) but they don't seem to have vertex degrees of freedom!?
+
+Indeed. And here's the reason: a vertex is an entity that is shared between different cells, i.e. it doesn't belong to one cell or another. If you have a shape function that is associated with it, then its support will extend to all of the cells that are adjacent to the vertex since no cell is different than any other cell. This is what happens, for example, with the `FE_Q(1)` element. The same is true, by the way, for degrees of freedom (and associated shape functions) that correspond to edges and faces between cells.
+
+But that doesn't answer the question of discontinuous elements. There, you have functions that are interpolation polynomials whose <i>support point</i> happens to be located at the same position as the vertex, but the actual support of the shape function is restricted to a single cell. In other words, '''logically''' these shape functions belong to a cell, not a vertex or edge or face, since the latter are all shared between adjacent cells. What this leads to is that, for example for the `FE_DGQ(1)` element, you have
+ - `fe.dofs_per_vertex` is zero
+ - `fe.dofs_per_line` is zero
+ - `fe.dofs_per_face` is zero
+ - `fe.dofs_per_cell` is 4 in 2d and 8 in 3d.
+In other words, all shape functions are associated with the cell interior.
+
+If this answer isn't quite satisfactory (because, after all, the shape functions <i>are</i> defined by interpolation at the location of the vertices), one could turn the question around: If you ask me for the degree of freedom associated with vertex 13, then I should ask you in return <i>which one</i> you have in mind since if there, say, four cells that meet at this vertex, then there will be 4 degrees of freedom defined there. Likewise, if you ask me for the value of the degree of freedom associated with vertex 13, then I should ask you in return <i>which one</i> as the function is discontinuous there and will have multiple values at the location of the vertex.
+
+## How do I access values of discontinuous elements at vertices?
+
+The previous question answered why DG elements aren't defined at the vertices of the mesh. Consequently, functions like `cell->vertex_dof_index` aren't going to provide anything useful. Nevertheless, there are occasions where one would like to recover values of a discontinuous field at the location of the vertices, for example to average the values one gets from all adjacent cells in recovery estimators.
+
+So how does one do that? The answer is: Getting the values at the vertices of a cell works just like getting the values at any other point of a cell. You have to set up a quadrature formula that has quadrature points at the vertices and then use an FEValues object with it. If you then use FEValues::get_function_values, you will get the values at all quadrature points (i.e. vertices) at once.
+
+Setting up this quadrature formula can be done in two different ways: (i) You can create an object of type `Quadrature` from a vector of points that you can initialize with the reference coordinates of the 2<sup>dim</sup> vertices of a cell; or (ii) you can use the `QTrapez` class that has its quadrature points in the vertices. In the latter case, however, you need to verify that the order of quadrature points is indeed the same order as the vertices of a cell and, if that is not the case, translate between the two numbering systems.
+
+## Does deal.II support anisotropic finite element shape functions?
+
+There is currently no easy-to-use support for this. It's not going to work for continuous elements because we assume that `fe.dofs_per_face` is the same for all faces of a cell.
+
+It may be possible to make this work for discontinuous elements, though. What you would have to do is define a bunch of different elements with anisotropic shape functions and select which element to use on which cells, using the `hp::DoFHandler` to deal with using different elements on different cells. The part that's missing is to implement elements with anisotropic shape functions. I imagine that this wouldn't be too complicated to do since the element is discontinuous, but someone would have to implement it.
+
+That said, you can do anisotropic <i>refinement</i>, which of course also introduces a kind of anisotropic approximation of your finite element space.
+
+## The graphical output files don't make sense to me -- they seem to have too many degrees of freedom!
+
+Let's assume you have a 2x2 mesh and a Q<sub>1</sub> element then you would assume that output files (e.g. in VTK format) just have 9 vertex locations and 9 values, one for each of the 9 nodes of the mesh. However, the file actually shows 16 vertices and 16 such values.
+
+The reason is that frequently output quantities in deal.II are discontinuous: it may be that the finite element in use is discontinuous to begin with; or that the quantity we want to output is defined on a cell-by-cell basis (e.g. error indicators) and therefore discontinuous; or that it is a quantity computed from a DataPostprocessor object that could be discontinuous. In order to not make things more complicated than necessary, deal.II <i>always</i> assumes that quantities are discontinuous, even if some of them may in fact be continuous. The problem is that all graphical formats want to see one value for each output field per vertex. But discontinuous fields have more than one value at the location of a vertex of the mesh. The solution to the problem is then to simply output each vertex multiple times -- with different vertex numbers but at exactly the same location, once for each cell it is adjacent to. In other words, in 2d, each cell has four unique vertices. The 2x2 mesh in the example therefore has 16 vertices (4 vertices for each of the 4 cells) and we output 16 values. Several of these vertices will have the same location and if the field is indeed continuous, several of the values will also be the same.
+
+## In my graphical output, the solution appears discontinuous at hanging nodes
+
+Let me guess -- you are using higher order elements? If that's the
+case, then the solution only looks discontinuous but isn't
+really. What's happening is that the solution is, in fact, a higher
+order polynomial (e.g., a quadratic polynomial) along each edge of a
+cell but because all visualization file formats only support writing
+data as bilinear elements we need to write data in a way that shows
+only a linear interpolation of this higher order polynomial along each
+edge. This is no problem if the two neighboring elements share the
+entire edge because then the linear interpolations from both sides
+coincide. However, if we have a hanging node, then the value at the
+hanging node appears to float above or below the linear interpolation
+from the longer side, like here (in the left picture, see the gap at
+the bottom in the blue green area, and around the top left in the
+greenesh area; pictures by Kevin Dugan):
+
+<img width="400px" src="http://www.dealii.org/images/wiki/gap-in-q2-1.png" align="center" />
+<img width="400px" src="http://www.dealii.org/images/wiki/gap-in-q2-2.png" align="center" />
+
+From this description you can already guess what the solution is: the
+solution is internally in fact continuous: even though we only show a
+linear interpolation on the long edge, the true solution actually goes
+through the "floating" node. All this is, consequently, just an
+artifact of the way visualization programs show data.
+
+If this bothers you or it simply looks bad in your graphics, you can
+lessen the problem by not plotting just a linear interpolation on each
+cell but outputting the solution as a linear interpolation on a larger
+number of "patches" per cell (e.g., plotting 5x5 patches per
+cell). This can be done by using the `DataOut::build_patches` function
+with an argument larger than one -- see its documentation.
+
+This all said, if you are in fact using a Q1 element and you see such
+gaps in the solution, then something is genuinely wrong. One
+possibility is that you forget to call `ConstraintMatrix::distribute`
+after solving the linear system, or you do not set up these
+constraints correctly. In either case, it's a bug if this happens with
+Q1 elements.
+
+## When I run the tutorial programs, I get slightly different results
+
+This is sometimes unavoidable. deal.II uses a number of iterative algorithms (e.g. in solving linear systems, but the adaptive mesh refinement loop is also an iteration if you think about it) where certain criteria are specified by comparing floating point numbers. For example, the CG method terminates the iteration whenever the residual drops below a certain threshold; similarly, we refine as many cells as are necessary to take care of a fraction of the total error. In both cases, the quantities that are compared are floating point numbers which are subject to floating point round off. The problem is that floating point round off depends on the processor (sometimes), compiler flags or randomness (if parallelization is involved) and consequently an a solver may terminate one iteration earlier or later, depending on your environment, than the one from which we produced our results. With a different solution typically come different refinement indicators and different meshes downstream.
+
+In other words, this is something that simply happens. What should worry you, however, is if you run the same program twice and you get slightly different output. This hints at non-deterministic effects that one should investigate.
+
+## How do I access the whole vector in a parallel MPI computation?
+
+Note that this causes a bottleneck for large scale computations and you should try to use a parallel vector with ghost entries instead. If you really need to do this, create a TrilinosWrappers::Vector (or a PETScWrappers::Vector) and assign your parallel vector to it (or use a copy constructor). You can find this being done in step-17 if you search for "localized_solution".
+
+## How to get the (mapped) position of support points of my element?
+
+Option 1: The support points on the unit cell can be accessed using FiniteElement::get_unit_support_point(s) and mapped to real coordinates using Mapping::transform_unit_to_real_cell()
+
+Option 2: DoFTools::map_dofs_to_support_points() maps all the support points at once.
+
+Option 3: You can create a FEValues object using the support points as a Quadrature:
+<pre>
+Quadrature<dim> q(fe.get_unit_support_points());
+FEValues<dim> fe_values (..., q, update_q_points);
+...
+fe_values.get_quadrature_points();
+</pre>
+
+
+# Debugging deal.II applications
+
+## I don't have a whole lot of experience programming large-scale software. Any recommendations?
+
+Yes. First, the questions of this FAQ already give you a number of good pointers for example on debugging. Also, a good resource for some of the questions mathematicians, scientists and engineers (who may have taken a programming course, but know little of the bigger world of software engineering) typically have, is the [Software Carpentry](http://software-carpentry.org/) page. That site is specifically targeted at people who may want to use scientific computing to solve particular applications, but have little or no formal training in dealing with large software. In other words, it is specifically written for people for an audience like the users of deal.II.
+
+
+## Are there strategies to avoid bugs in the first place?
+
+Why yes, good you ask. There are indeed techniques that help you avoid writing code that has bugs. By and large, these techniques go by the name <i>defensive programming</i>, and the idea is to get yourself into a mindset while programming that anticipates that you will make mistakes, rather than expecting that your code is correct and then reacting to the situation when it turns out that this isn't true. The point is that even the most experienced programmers do introduce a lot of bugs into their code; what makes them good is that they have strategies to find them quickly and systematically.
+
+Below we show one of the most important lessons learned. A more complete list can be found in [our code conventions page](http://dealii.org/developer/doxygen/deal.II/CodingConventions.html) which has a collection of best practices including code snippets to show how they are used.
+
+The single most successful strategy to avoid bugs is to <i>make assumptions explicit</i>. For example, assume for a second that you have a class that denotes a point in 3d space:
+```
+  class Point3d {
+    public:
+      double coordinate (const unsigned int i) const;
+      // ...more here...
+    private:
+      double coordinates[};
+
+  double
+  Point3d::coordinate (const unsigned int i) const {
+    return coordinates[i](3];);
+  }
+```
+
+Here, when we wrote the `coordinate()` function, we worked under the assumption that the index `i` is between zero and two. As long as that assumption is satisfied, everything is fine. The problems start when someone calls this function with an index greater than two -- the function will in that case simply return garbage, but that may not be immediately obvious and may only much later lead to weird results in your program. Inexperienced programmers will say "Why would I do that, it doesn't make any sense!". Defensive programming starts from the premise that this is something that simply <i>will happen</i> at one point in time, whether you want to or not. It's actually not very difficult to do, since all of us have probably written code like this:
+```
+  Point3d point;
+  // ... do something with it
+  double norm = 0;
+  for (unsigned int i=0; i<=3; ++i)
+    norm += point.coordinate(i) ** point.coordinate(i);
+  norm = std::sqrt(norm);
+```
+
+Note that we have accidentally used `<=` instead of `<` in the loop.
+
+If we accept that bugs will happen, we should make it as simple as possible to find them. In the spirit of making assumptions explicit, let's write above function like this:
+```
+  double
+  Point3d::coordinate (const unsigned int i) const {
+    if (i >= 3) {
+      std::cout << "Error: function called with invalid argument!" << std::endl;
+      std::abort ();
+    }
+    return coordinates[}
+```
+
+This has the advantage that an error message is produced whenever the function is called with invalid arguments, and for good measure we also abort the program to make sure the error message can really not be missed in the rest of the output of the program. The disadvantage is that this check will always be performed whenever the program runs, even if it is well tested and we are fairly certain that in all places where the function is called, indices are valid. To avoid this drawback, the C programming language has the `assert` macro, which expands to the code above by default, but that can be disabled using a compiler flag. deal.II provides an improved version of this macro that is used as follows:
+```
+  double
+  Point3d::coordinate (const unsigned int i) const {
+    Assert (i<3, ExcMessage ("Function called with invalid argument!"));
+    return coordinates[i](i];);
+  }
+```
+
+The macro expands to nothing in optimized mode (see below), and if it is triggered in debug mode it doesn't only abort the program, but also prints an error message and shows how we got to this point in the program.
+
+Using assertions in your program is the single most efficient way to make assumptions explicit and help find bugs in your program as early as possible. If you are looking for some more background, check out the wikipedia articles on [assertions](http://en.wikipedia.org/wiki/Assertion_(computing)), [preconditions](http://en.wikipedia.org/wiki/Precondition) and [postconditions](http://en.wikipedia.org/wiki/Postcondition), and generally the [design by contract methodology](http://en.wikipedia.org/wiki/Design_by_contract).
+
+## How can deal.II help me find bugs?
+
+In addition to using the `Assert` macro introduced above, the deal.II libraries come in two flavors: debug mode and optimized mode. The difference is that the debug mode libraries contain a lot of assertions that verify the validity of parameters you may pass when calling library functions and classes; the optimized libraries don't contain these and are compiled with flags that instruct the compiler to optimize. This makes executables linked against the optimized libraries between 4 and 10 times faster. On the other hand, you will find that you will find 90% or more of your bugs by using the debug libraries because most bugs simply pass data to other functions that they don't expect or that don't make sense. The consequence is that you should always use debug mode when you are still developing your code. Only when it runs without bugs -- and under no circumstances any earlier -- should you switch to optimized mode to do production runs. One of the silliest things you can do is switch to optimized mode because you otherwise get an error you can't make sense of and that you don't know how to fix; certainly, if the library complains about something and you ignore it, nothing good can come out of the remainder of the run of your program.
+
+To switch between debug and optimized mode, take a look at the top of the deal.II-provided Makefiles: there's a flag you can set that switches between the two modes.
+
+## Should I use a debugger?
+
+This question has an emphatic, unambiguous answer: Yes! You may get by for a while by just putting debug
+output into your program, compiling it, and running it, but ultimately finding
+bugs with a debugger is much faster, much more convenient, and more reliable
+because you don't have to recompile the program all the time and because you
+can inspect the values of variables and how they change.
+Learn how to use a debugger as soon as
+possible. It is time well invested.
+
+Debuggers come in a variety of ways. On Linux and other Unix-like operating systems, they are almost all based in one way or other on the [GNU Debugger (GDB)](http://www.gnu.org/s/gdb/). GDB itself is a tool that is driven by interactively typing commands; if you know your way around with it, it is quite useable but it is rather austere and unless you are already familiar with this style of debugging, don't learn it. Rather, you should either use a graphical front-end or, even better, a front-end to GDB that is integrated into an Integrated Development Environment (IDE). An example of the stand-alone graphical front-ends to GDB are [DDD](http://www.gnu.org/software/ddd/), a program that was the first of its kind on Linux for many years but whose development has pretty much ceased in the early 2000s; it is still quite a good program, though. Another example is [KDbg](http://kdbg.org/), a GDB front-end for the KDE desktop environment.
+
+As mentioned, a better choice is to use a debugger front-end that is integrated into the IDE. Every decent IDE has an integrated debugger, so you have your choice. A list of IDEs and how they work with deal.II is given in the C++ section of this FAQ.
+
+## deal.II aborts my program with an error message
+
+You are likely seeing something like the following:
+```
+--------------------------------------------------------
+An error occurred in line <1302> of file </u/bangerth/p/deal.II/1/deal.II/include/deal.II/lac/vector.h> in function
+    Number& dealii::Vector<Number>::operator()(unsigned int) [Number = double](with)
+The violated condition was:
+    i<vec_size
+The name and call sequence of the exception was:
+    ExcIndexRange(i,0,vec_size)
+Additional Information:
+Index 10 is not in [Stacktrace:
+-----------
+#0  ./step-1: dealii::Vector<double>::operator()(unsigned int)
+#1  ./step-1: foo()
+#2  ./step-1: main
+--------------------------------------------------------
+```
+
+This error is generated by the following program:
+```
+#include <lac/vector.h>
+using namespace dealii;
+
+void foo ()
+{
+  Vector<double> x(10);
+  for (unsigned int i=0; i<=x.size(); ++i)
+    x(i) = i;
+}
+
+
+int main ()
+{
+  foo ();
+}
+```
+
+So what to do in a case like this? The first step is to carefully read what the error message actually says as it contains pretty much all the information you need. So let's take the error message apart:
+
+ - The first two lines tell you where the problem happened: in the current case, in line 1302 of file `/u/bangerth/p/deal.II/1/deal.II/include/deal.II/lac/vector.h` in function `Number& dealii::Vector<Number>::operator()(unsigned int) [with Number = double](0,10[)`. This is a function in the library, so you likely don't know what exactly it does and what to do with it, but there is more information to come.
+
+ - The second part is the condition that should have been true but wasn't, leading to the error: `i<vec_size`. The variables involved in this condition (`i,vec_size`) are local variables of the function, or member variables of the class, so again you may not be entirely familiar with them. But you can already gather some of the information: `i` likely is an index, which should have been less than the variable `vec_size` (which sounds a lot like the length of a vector); the assertion says that it <i>should</i> have been smaller, but that it wasn't actually.
+
+ - There is more information: The exception generated is of kind `ExcIndexRange(i,0,vec_size)` and the additional information says `Index 10 is not in [In other words, the variable `i` has value 10, and `vec_size` is also ten. This should already give you a fairly good idea what is happening: the vector has size ten, and following C array convention, that means that only indices zero through nine are value, but ten is not.
+
+ - The final part of the error message -- the stack trace -- tells you how you got to this place: reading from the bottom, `main()` called `foo()` which called the function that generated the error.
+
+Taken together, this information should allow you figure out in 80% of cases what was going on, and fix the problem. Here, it is that we used the condition `i<=x.size()` in the loop, rather than the correct condition `i<x.size()`. In the remaining 20% of cases, things might be more difficult. For example, `foo()` might be a large and difficult function, and you would need to know in which part of the function did we access an invalid index of the vector. Or `i` was an index computed from other variables and you'd need to find out why it got the invalid value. In these cases, you'll have to learn how to use a debugger such as gdb, and in particular how to move up and down in the call stack and to inspect local variables in your source code.
+
+## The program aborts saying that an exception was thrown, but I can't find out where
+
+deal.II creates two kinds of exceptions (in deal.II language): ones where we
+simply abort the program because you are doing something that can't be right
+(such as accessing element 11 of a 10-element vector; this results in what has
+been discussed in the previous question) and ones that use the C++ construct
+`throw` to raise an exception. The latter construct is used for things that
+can't be statically checked in debug mode because they may depend on values
+read from input files or on a status that may simply change from one run of
+the program to the next; consequently, they <i>always</i> need to be verified,
+not only in debug mode, and there is sometimes a way to work around it in a
+program. The typical case is trying to write to a file that can't be opened
+(e.g. because the directory/file you specified in a parameter file doesn't
+exist or because the file system has run out of disk space).
+
+Most of the time, the exceptions deal.II throws are annotated with the
+location and function where this exception was raised, and if you use a
+`main()` function such as the one used starting in step-6, this information
+will be printed. However, there are also cases where this kind of information
+is not available and then it is often difficult to establish where exactly the
+problem is coming from: all you know is that an exception was thrown, but not
+where or why.
+
+To debug such problems, two approaches have proven useful:
+
+ - Run your program in a debugger (see the question about debuggers above, as well as these videos showing how to use the debugger in 22c8e221823811aa1178b450171824af: http://www.math.tamu.edu/~bangerth/videos.676.8.html, http://www.math.tamu.edu/~bangerth/videos.676.25.html). You need to instruct the debugger to stop whenever an exception is thrown. If you work with gdb on the command line, then issue the command `catch throw` before starting the program and it will stop everytime the code executes a `throw` statement. Integrated development environments typically also have ways of switching this on. Note that not every exception that is thrown actually indicates an error -- sometimes, there are legitimate reasons to throw an exception and catch it in the calling function, so you may have to continue (resume) a number of times before finding the place where this happens.
+
+ - Debugging by subtraction: Starting at the end of your program, remove one function/code block after the other until your program runs through without aborting. For example, if your program looked like step-6, see if it runs through if you don't create graphical output in `run()`. If it does, then you know that the exception must have been thrown in the block of code you just removed. If the program continues to abort, then reduce the number of mesh refinement cycles to find out withhin which cycle the problem happens. If it happens in the very first cycle, then remove calling the linear solver. If the program now runs through, then the problem happened in the solver. If it still aborts, then it must have happened before the solver, for example in the assembly. Repeating this, you will be able to narrow down which statement caused the problem, and knowing where a problem happens is already more than half of what you need to know to fix it.
+
+
+## I get an exception in `virtual dealii::Subscriptor::~Subscriptor()` that makes no sense to me!
+
+The full text of the error message probably looks something like this (the stack trace at the bottom is of course different in your code):
+```
+An error occurred in line <103> of file </.../deal.II/source/base/subscriptor.cc> in function
+    virtual dealii::Subscriptor::~Subscriptor()
+The violated condition was:
+    counter == 0
+The name and call sequence of the exception was:
+    ExcInUse (counter, object_info->name(), infostring)
+Additional Information:
+Object of class N6dealii15SparsityPatternE is still used by 5 other objects.
+  from Subscriber SparseMatrix
+
+Stacktrace:
+-----------
+#0  /.../deal.II/lib/libdeal_II.g.so.7.0.0: dealii::Subscriptor::~Subscriptor()
+#1  /.../deal.II/lib/libdeal_II.g.so.7.0.0: dealii::SparsityPattern::~SparsityPattern()
+#2  /.../deal.II/lib/libdeal_II.g.so.7.0.0: dealii::BlockSparsityPatternBase<dealii::SparsityPattern>::reinit(unsigned int, unsigned int)
+#3  /.../deal.II/lib/libdeal_II.g.so.7.0.0: dealii::BlockSparsityPattern::reinit(unsigned int, unsigned int)
+#4  /.../deal.II/lib/libdeal_II.g.so.7.0.0: dealii::BlockSparsityPattern::copy_from(dealii::BlockCompressedSimpleSparsityPattern const&)
+#5  ./step-6: NavierStokesProjectionIB<2>::setup_system()
+#6  ./step-6: NavierStokesProjectionIB<2>::run(bool, unsigned int)
+#7  ./step-6: main
+```
+
+What is happening is this: deal.II derives a bunch of classes from the `Subscriptor` base class and then uses the `SmartPointer` class to point to such objects. `SmartPointer` is actually a fairly simple class: when given a pointer, it increases a counter in the `Subscriptor` base of the object pointed to by one, and when the pointer is reset to another object or goes out of scope, it decreases the counter again. (It can also records <i>who</i> points to this object.) If someone tries to delete the object pointed to, then the destructor `dealii::Subscriptor::~Subscriptor()` is run and checks that in fact the counter in this object is zero, i.e. that nobody is pointing to the object any more -- because if some pointer was still pointing to it, it would be a poor decision to delete the object as then the pointer would point to invalid memory. If the counter is nonzero, you get the error above: you are trying to delete an object that is still pointed to. In the case above, you try to delete a `SparsityPattern` object (that is, from the stack trace, a part of a block sparsity pattern) even though there is still a `SparseMatrix` pointing to it (we get this from the "Additional Information" field).
+
+The solution in cases like these is to make sure that at the time you delete the object, no other objects still have pointers that point to it.
+
+There is one rather frequent case that results in an error like the above and that is often difficult to understand: if an exception is thrown in some function and not caught, all local objects are destroyed in the opposite order of their declaration; if it isn't caught in the function that called the place where the exception was generated, its local variables are also destroyed, and so on. This automatic destruction of objects typically bypasses all the clean-up code you may have at the end of a function and can then lead to errors like the above. For example, take this code:
+```
+void f() {
+  SparseMatrix s;
+  SparsityPattern sp;
+  // initialize sp somehow
+  s.reinit (sp);
+  Vector v;
+  // build a linear system
+
+  solve_linear_system (s, v);
+
+  s.reinit ();
+}
+```
+
+If the code executes normally, at the bottom of the function, the local variables `s,sp,v` will be destroyed in reverse order. Since we have called `s.reinit()`, the object no longer stores a pointer to `sp` and so destruction of `sp` before `s` incurs no harm. But if the function `solve_linear_system` throws an exception, for example because the linear system is singular, the call to `s.reinit()` isn't executed any more, and you will get an error like the one shown at the top.
+
+In cases like these, the challenge becomes finding where the exception was thrown. The easiest way is to run your program in a debugger and let the debugger tell you whenever an exception is generated. In `gdb`, you can do that by saying `catch throw` before running the program; essentially, the command puts a breakpoint on all places where exceptions are thrown. Remember, however, that not every place where an exception is thrown is a candidate for the problem above: it may also be an exception that is caught in the function above and that never propagates to a point where it produces trouble. Consequently, it may well happen that you have to continue several times after seeing an exception thrown until you finally find the place where the offending exception happens.
+
+## I get an error that the solver doesn't converge. But which solver?
+
+Solvers are often deeply nested -- take a look for example at step-20 or step-22, where there is an outer solver for a Schur complement matrix, but both in the implementation of the Schur complement as well as in the implementation of the preconditioner we solve other linear problems which themselves may have to be preconditioned, etc. So if you get an exception that the solver didn't converge, which one is it?
+
+The way to find out is to not wait till the exception propagates all the way to `main()` and display the error code there. Rather, you probably don't have a Plan B anyway if a solver fails, so you may want to abort the program if that happens. To do this, wrap the call to the solver in a try-catch block like this:
+```
+  try {
+    cg.solve (system_matrix, solution, system_rhs, preconditioner);
+  } catch (...) {
+    std::cerr << "*** Failure in Schur complement solver! ***" << std::endl;
+    std::abort ();
+  }
+```
+
+Of course, if this is in the Schur preconditioner, you may want to use a different error message. In any case, what this code does is catch the exceptions thrown by the solver here, or by the system matrix's `vmult` function (if not already caught there) or by the preconditioner (if not already caught there). If you had already caught exceptions in the `vmult` function and in the preconditioner, then you now know that any exception you get at this location must have been because the CG solver failed, not the preconditioner, etc. The upshot is that you need to wrap <i>every</i> call to a solver with such a try-catch block.
+
+## How do I know whether my finite element solution is correct? (Or: What is the "Method of Manufactured Solutions"?)
+
+This is not always trivial, but there is an "industry-standard" way of verifying that your code works as intended, called the '''method of manufactured solutions'''. Before we describe the method, let us point this out: '''A code that has not been verified (i.e. for which correctness has not been established) is worthless. You do not want to have results in your thesis or a publication that may later turn out to be incorrect because your code does not converge to the correct solution!'''
+
+The idea to verify a code is that you need a problem for which you know the exact solution. Unless you solve the very simplest possible partial differential equations, it is typically not possible to choose a right hand side and boundary values and then find the corresponding solution to the PDE analytically, on a piece of paper. But you can turn this around: Let's say your equation is <i>Lu=f</i>, then choose some function <i>u</i> and compute <i>f=Lu</i>. Note that the solution <i>u</i> does not necessarily have to be something that looks like a useful or physically reasonable solution to the equation, all that is necessary is that it is a function you know. Because <i>L</i> is a differential operator, computing <i>f</i> only involves computing the derivatives of the known function; this may yield lengthy expressions if you have nonlinearities or spatially variable coefficients in the equation, but should not be too complicated and can also be done using computer algebra programs such as Maple or Mathematica.
+
+If you now put this particular right hand side <i>f</i> into your program (along with boundary values that correspond to the values of the function <i>u</i> you have chosen) you will get a numerical solution <i>u<sub>h</sub></i> that we would hope converges against the exact solution <i>u</i> at a particular rate, say <i>O(h<sup>2</sup>)</i> in the <i>L<sub>2</sub></i> norm. But since you know the exact solution (you have chosen it before), you can compute the error between numerical solution and exact solution, and verify not only that your code converges, but also that it shows the convergence rate you expect.
+
+The method of manufactured solutions is shown in the step-7 tutorial program.
+
+## My program doesn't produce the expected output!
+
+There are of course many possible causes for this, and you need to find out which of these causes might be the reason. Possible places to start are:
+
+ - Are matrix and right hand side assembled correctly? For most reasonably simple problems, you can compute the local contributions to these matrices by hand, and then compare those with the ones you compute on every cell of your program (remember that you can print the contents of the local matrix and right hand side to screen). A good strategy is also to reduce your problem to a 1x1 or 2x2 mesh and then print out the entire system matrix for comparison.
+
+ - Do you compute the matrix you need, or its transpose? The mathematical literature often multiplies the equation from the right with a test function but that is awkward because the matrix you get this way is the transpose from the one you need. The deal.II documentation goes to lengths in multiplying test functions from the left to avoid this sort of error; do the same in your derivations.
+
+ - Your constraints or boundary values may be wrong. While the ConstraintMatrix and functions like VectorTools::interpolate_boundary_values are well enough tested that they are unlikely candidates for problems, you may have computed constraints wrongly if you collect them by hand (for example if you deal with periodic boundary conditions or similar) or you may have specified the wrong boundary indicator for a Dirichlet boundary condition. Again, the solution is to reduce the problem to the simplest one you can find (e.g. on the 1x1 or 2x2 mesh talked about above) and to ask the ConstraintMatrix to print its contents so that you can compare it by hand with your expectations.
+
+ - Your discretization might be wrong. Some equations require you to use particular (combination of) finite elements; for example, for the Stokes equations and many other saddle point problems, you need to satisfy an LBB or Babuska-Brezzi condition. For other equations, you need to add stabilization terms to the bilinear form; for example, advection or transport dominated problems require stabilization terms such as artificial diffusion, streamlinear diffusion, or SUPG.
+
+ - The solver might be wrong. This can reasonably easily happen if you have a complex solver such as, for example, the one used in step-22. In such cases it has proven useful to simply replace the entire solver by the sparse direct UMFPACK solver (see step-29). UMFPACK is not the fastest solver around, but it never fails: if the linear system has a solution, UMFPACK will find it. If the output of your program is essentially the same as before, then the solver wasn't your problem.
+
+ - Your assumptions may be wrong. Double check that you had the correct right hand side to compute the numerical solution you compare against your analytical one. Also remember that the numerical solution is usually only an approximation of the true one.
+
+In general, if your program is not computing the output you expect, here are a few strategies that have often worked in finding the problem:
+ - Take a good look at the output you get. For example, a close look can already tell you if (i) the boundary conditions are correct, (ii) the solution is continuous at hanging nodes, (iii) the solution follows the characteristics of the right hand side. This may already help you narrow down which part of the program may be the culprit. A common mistake is also to have a solution that by some accident is too large by a certain factor; consequently, the error will not converge to zero but to some constant value. This, again, is easily visible from a graphical representation of the solution and/or the error. Plotting the error is discussed in the section below entitled "How to plot the error as a pointwise function".
+ - If you have a time dependent problem, is the first time step right? There is no point in running the program for 1000 time steps and trying to find our why it is wrong, if already the first time step is wrong.
+ - If you still can't find what's going on, make the program as small as possible. Copy it to another directory and start stripping off parts that you don't need. For example, if it is a time dependent program for which you have previously already found out that the first time step is wrong, then remove the time loop. If you have tried whether you have the same problem when the mesh is uniformly refined, then throw out all the code that deals with adaptive refinement, constraints and hanging nodes. In this process, every time you simplify the program, verify that the problem is still there. If the problem disappears, you know that it must have been in the last simplification step. If the problem remains, it must be in the code that is now one step smaller. Ultimately, the code should be small enough so that you can just go through it and find the error by inspection.
+ - Learn to use a debugger. You will find that using a debugger is so much more convenient than trying to put screen output statements into your code, recompiling, and hoping that they reveal the problem. Modern integrated development environment as the ones discussed elsewhere in this FAQ have the debugger built-in, allowing you to use it seamlessly in your editing environment.
+
+## The solution converges initially, but the error doesn't go down below 10<sup>-8</sup>!
+
+First: if the error converges to zero, then you are basically doing something right already. Congratulations!
+
+As for why the error does not converge any further, there are two typical cases what could be the reason:
+
+ - While the discretization error should converge to zero, the error of your numerical solution is composed of both the discretization error and the error of your linear or nonlinear solver. If, for example, you solve the linear system to an accuracy of 10<sup>-5</sup>, then there will be a point where the discretization error will get smaller than that by using finer and finer meshes but the solver error will not become smaller any more. To continue observing the correct convergence order, you will also have to solve the linear system with more accuracy.
+
+ - If you compute the error through an external program, for example by writing out the solution to a file and reading it from another program that knows about the exact solution, then you need to make sure you write the solution with sufficient accuracy. The default setting of C++ writes floating point numbers with approximately 8 digits, so if you want to make sure that your solution is correct to 10<sup>-10</sup>, for example, you'll have to write out the solution with more than 10 digits.
+
+## My time dependent solver does not produce the correct answer!
+
+For time dependent problems, there are a number of other things you can try over the discussion already given in the previous answer. In particular:
+
+ - If you have a time iteration and the solution at the final time (where you may evaluate the error) is wrong, then it was likely already wrong at the first time step. Try to run your program only for a single time step and make sure the solution there is correct. For example, it could be that you set the boundary values wrongly; this would be quite apparent if you looked at the first time step because the effect would be largest close to the boundary, but it may no longer be visible if you ran your program for a couple hundred time steps.
+
+ - Are your initial values correct? Output the initial values using DataOut just like you output the solution and inspect it for correctness.
+
+ - If you have a multi-stage time stepping scheme, are *all* the initial values correct?
+
+ - Finally, you can test your scheme by setting the time step to zero. In that case, the solution at time step zero should of course be equal to the solution at time step zero. If it isn't, you already know better where to look.
+
+## My Newton method for a nonlinear problem does not converge (or converges too slowly)!
+
+Newton methods are tricky to get right. In particular, they sometimes converge (if slowly) even though the implementation has a bug because all that is required for convergence is that the search direction is a direction of descent; consequently, if for example you have the wrong matrix, you may compute something that is a direction of descent, but not the full Newton direction, and so converges but not at quadratic order.
+
+Here are a few considerations for implementing Newton's method for nonlinear PDEs:
+
+ - Try it with a linear program by removing all the nonlinearities in your problem. Your Newton iteration must converge in a single step, i.e. the Newton residual must be zero at the beginning of the second iteration. If that's not the case, something is wrong in your implementation.
+
+ - Newton's iteration will converge with optimal order for the problem `F(u)=0` if you <i>consistently</i> compute the Newton residual `(F(u<sup>k</sup>), &phi;<sup>i</sup>)` and the Newton (Jacobian) matrix `(F'(u<sup>k</sup>) &phi;<sup>j</sup>, &phi;<sup>i</sup>)`. If you have a bug in either of the two, your method may converge, but typically at a (much) lower rate and with consequently many more iterations. Consequently, one way to debug Newton's methods is to verify that Newton matrix and Newton residual are matching in their code. However, if you have a matching bug in <i>both</i> of the matrix and right hand side assembly, then your Newton method will converge with correct order but against the wrong solution.
+
+ - If you have nonzero boundary values for your problem, set the correct boundary values for the initial guess and use zero boundary values for all following updates. This way, the updated `u<sup>k+1</sup> = u<sup>k</sup> + &delta; u<sup>k+1</sup>` already has the right boundary values for all following iterations.
+
+ - If your problem is strongly nonlinear, you may need to employ a line search where you compute `u<sup>k+1</sup> = u<sup>k</sup> + &alpha; &delta; u<sup>k+1</sup>` and successively try &alpha;=1, &alpha;=1/2, &alpha;=1/4, etc until the residual computed for `u<sup>k+1</sup>` for this &alpha; is smaller than the residual for `u<sup>k</sup>`.
+
+ - A rule of thumb is that if your problem is strongly nonlinear, you may need 5 or 10 iterations with a step length &alpha; less than one, and all following steps use the full step length &alpha;=1.
+
+ - For most reasonably behaved problems, once your iteration reaches the point where it takes full steps, it usually converges in 5 or 10 more iterations to very high accuracy. If you need significantly more than 10 iterations, something is likely wrong.
+
+## Printing deal.II data types in debuggers is barely readable!
+
+Indeed. For example, plain gdb prints this for cell iterators:
+```
+$2 = {<dealii::TriaIterator<dealii::DoFCellAccessor<dealii::DoFHandler<2, 3> > >> = {<dealii::TriaRawIterator<dealii::DoFCellAccessor<dealii::DoFHandler<2, 3> > >> = {<std::iterator<std::bidirectional_iterator_tag, dealii::DoFCellAccessor<dealii::DoFHandler<2, 3> >, long, dealii::DoFCellAccessor<dealii::DoFHandler<2, 3> >*, dealii::DoFCellAccessor<dealii::DoFHandler<2, 3> >&>> = {<No data fields>},
+      accessor = {<dealii::DoFAccessor<2, dealii::DoFHandler<2, 3> >> = {<dealii::CellAccessor<2, 3>> = {<dealii::TriaAccessor<2, 2, 3>> = {<dealii::TriaAccessorBase<2, 2, 3>> = {
+                static space_dimension = <optimized out>, static dimension = <optimized out>,
+                static structure_dimension = <optimized out>, present_level = -9856,
+                present_index = 32767, tria = 0x4a1556}, <No data fields>}, <No data fields>},
+          static dimension = 2, static space_dimension = 3, dof_handler = 0x7fffffffdac8},
+        static dim = <optimized out>,
+        static spacedim = <optimized out>}}, <No data fields>}, <No data fields>}
+```
+
+Fortunately, this can be simplified to this:
+```
+$3 = {
+  triangulation = 0x4a1556,
+  dof_handler = 0x7fffffffdac8,
+  level = 2,
+  index = 52
+}
+```
+
+All you need is (i) gdb version 7.1 or later, or a graphical frontend for it (e.g. [http://www.gnu.org/software/ddd/ DDD](0,10[`.) or [kdevelop](http://www.kdevelop.org)), (ii) some code that goes into your $HOME/.gdbinit file. This file, implementing pretty printers for the `Point, Tensor, Vector` and the various iterator classes for triangulations and DoFHandlers is posted [here](gdbinit).
+
+gdb can also pretty print many of the `std::XXX` classes, but not all linux distributions have it configured this way. To enable this, follow the instructions [from this website](http://sourceware.org/gdb/wiki/STLSupport). The little python snippet can be placed as a separate python block into `.gdbinit`.
+
+## My program is slow!
+
+This is a problem that is true for a lot of us. The question is which part of your program is causing it. Before going into more detail, there are, however, some general observations:
+
+ - Running deal.II programs in debug mode will take, depending on the program, between 4 and 10 times as long as in optimized mode. If you are using the deal.II Makefiles, you can switch between debug and optimized mode somewhere at the top of the Makefile.
+
+ - A typical finite element program will spend around one third of its time in assembling linear systems, around one half in solving these linear systems, and the rest of the time on other things. If your program's percentages significant deviate from this rule of thumb, you know where to start.
+
+ - There is a rule that says that even the best programmers are unable to point out where in the program the most CPU time is spent without some form of profiling. This is definitely true also for the primary developers of deal.II, so it is likely true for you as well. A corollary to this rule is that if you start optimizing parts of your code without first profiling it, you are more than likely just going to make things more complicated without significant gains because you pick the simplest places to optimize, not the ones with the biggest impact.
+
+So how can you find out which parts of the program are slow? There are two tools that we've really come to like, both from the [valgrind](http://www.valgrind.org/) project: callgrind and cachegrind. Valgrind essentially emulates what your CPU would do with your program and in the process collects all sorts of information. In particular, if you run your program as in
+```
+  valgrind --tool=callgrind ./myprogram
+```
+
+(this will take around 10 times longer than when you just call `./myprogram` because of the emulation) then the result will be a file in this directory that contains information about where your program spent its time. There are a number of graphical frontends that can visualize this data; my favorite is `kcachegrind` (a misnomer -- it is, despite its name, actually a frontend from callgrind, not cachegrind). Pictures of how this output looks can be found in the introduction of step-22. It typically shows how much time was spent in each function and a call graph of which functions where called from where.
+
+Using valgrind's cachegrind can give you a more detailed look at much of the same kind of information. In particular, it can show you source line for source line how many instructions were executed there, and how many memory accesses (as well as cache hits and misses) were generated there. See the valgrind manual for more information.
+
+Lastly, since you are probably most interested in the performance of the optimized version of your code (which you will probably use for long expensive runs), you should run valgrind on the optimized executable.
+
+## How do I debug MPI programs?
+
+This is clearly an awkward topic for which there are few good options: debugging parallel programs using MPI has always been a pain and it is frustrating even to experienced programmers. That said, there are parallel debuggers that can deal with MPI, for example [TotalView](http://www.roguewave.com/products/totalview-family/totalview.aspx) that can make this process at least somewhat simpler.
+
+Whether you have or don't have TotalView, here are a few guidelines of strategies that have helped us in the past:
+
+ - Try to reduce the problem to the smallest one you can find: The smallest mesh, the smallest number of processors. Reducing the number of processors needed to demonstrate the bug must be your highest priority.
+
+ - One of the biggest problems you typically have is that the processes that communicate via MPI typically run on different machines. If you can manage to reduce the problem to a small enough number of processors, you can run them all locally on a single workstation, rather than a cluster of computers. Ideally, you would reduce the problem to 2 or 4 processors and then just start the program using `mpirun -np 4 ./myexecutable` on the headnode of the cluster, a workstation, or even a laptop.
+
+ - Try to figure out which MPI process (the MPI rank) has the problem, for example by printing the output of `Utilities::System::get_this_mpi_process(MPI_COMM_WORLD)` at various points in your program.
+
+ - If you know which MPI process has the problem and if this is reproducible, let each process print out its MPI rank and its process id (PID) using the system function `getpid` at the very beginning of the program. The PID is going to be different every time you run the program, but if you know the connection between MPI rank and PID and you know which rank will produce the problem, then you can predict which PID will have the problem. The point of this is that you can attach a debugger to this PID; for example, `gdb` has the command `attach <pid>` with which you can attach the debugger to a running program, rather than running the program from the start within the debugger. Attaching a program to the debugger will stop it (and, after a while, will typically also stop all the other MPI processes once they come to a place where they are waiting for a communication from the stopped process). You can then look at variables, continue running to breakpoints, or do whatever else you want to do with the process you attached the debugger to. In particular, if for example you attached the debugger to the process that you know will segfault or run onto a failing assertion, you can just type `continue` in the debugger to let the program continue till it aborts. You can then inspect the state of the program at the point of the problem inside the debugger you attached.
+
+ - The above process relies on the fact that you have time to attach a debugger between starting the program, reading the mapping from MPI process rank to PID, and attaching a debugger. If the program produces the error very quickly, it is often useful to insert a call to `sleep(60);` (and including the appropriate header file) just after outputting MPI rank and PID. This gives you 60 seconds to attach the debugger before the program will continue.
+
+ - If finding out which MPI process has the problem turns out to be too complicated, or if it isn't predictable which process will produce an error, then there is a fallback option: attach a debugger to <i>every</i> MPI process. This is awkward to do by hand, but there is a shortcut: at least under linux (or any other unix system) you can run the program as in
+```
+  mpirun -np 4 xterm -e gdb ./my_executable
+```
+
+In this example, we start 4 MPI processes; in each of these 4 processes, we open an `xterm` window in which we start an instance of `gdb` with the executable. You'd then `run` the executable in each of the 4 windows, and debug it as you usually would. This might be tedious but as mentioned above, debugging MPI programs often is tedious indeed. To find out which gdb window belongs to which MPI rank, you can type the command
+```
+  !export | grep RANK
+```
+into the gdb window (this works with openmpi at least).
+
+## I have an MPI program that hangs
+
+Apart from programs that segfault or that run onto a failing assertion (both cases that are relatively easy to debug using the techniques above), programs that just hang are the most common problem in parallel programming. The typical cause for this is that there is a point in your program where all or some MPI processes expect to get a message from a process X (e.g. in a global communication, say MPI_Reduce, MPI_Barrier, or directly in point-to-point communications) but process X is not where it should be -- for example, because it is in an endless loop, or -- more likely -- because process X didn't think that it should participate in this communication. In either case, the other processes will wait forever for process X's message and deadlock the program. An example for this case would go like this:
+```
+  void assemble_system () {
+              // optimization in case there is nothing to do; we won't
+              // have to initialize FEValues and other local objects in
+              // that case
+    if (tria.n_locally_owned_active_cells() == 0)
+      return;
+
+    ...
+    for (cell = ...)
+      if (!cell->is_ghost() && !cell->is_artificial())
+        ...do the assembly on the locally owned cells...
+
+    system_rhs.compress();
+  }
+```
+
+Here, the call to `compress()` at the end involves communication between MPI processes. In particular, say, it implies that process Y will wait for some data from process X. Now what happens if process X realizes that it doesn't have any locally owned cells? In that case, process X will quit the function at the very top, and will never call `compress()`. In other words, process Y will wait forever, possibly making process Z wait further down the program etc. In the end, the program will be deadlocked.
+
+The goal of debugging the program must be to find where individual processes are stopped in order to determine which incoming communication they are waiting for. If you attached a debugger to the program above, you'd find for example that all but one process is stopped in the call to `compress()`, and the one remaining process is stopped in some other MPI call, then you already have a good idea what may be going on.
+
+## One statement/block/function in my MPI program takes a long time
+
+Let's say you have a block of code that you suspect takes a long time and you want to time it like this:
+```
+  Timer t;
+  t.start();
+  my_function();
+  t.stop();
+  if (my MPI rank == 0)
+    std::cout << "Calling my_function() took " << timer() << " seconds." << std::endl;
+```
+
+The output is large, i.e. you think that the function you called is taking a long time to execute and that you should focus your efforts on optimizing it. But in an MPI program, this isn't quite always true. Imagine, for example, that the function looked like this:
+```
+  void my_function () {
+    double val = compute_something_locally();
+    double global_sum = 0;
+    MPI_Reduce (&val, &global_sum, MPI_DOUBLE, 1, 0, MPI_COMM_WORLD);
+    if (my MPI rank == 0)
+      std::cout << "Global sum = " << global_sum << std::endl;
+  }
+```
+
+In the call to `MPI_Reduce`, all processors have to send something to processor zero. Processor zero will have to wait till everyone sends stuff to this processor. But what if processor X is still busy doing something else (stuff above the call to `my_function`) for a while? The processor zero will wait for quite a while, not because the operations in `my_function` are particularly expensive (either on processor zero or processor X) but because processor X was still busy doing something else. In other words: you need to direct your efforts in making the "something else on processor X" faster, not making `my_function` faster.
+
+To find out whether this is really the problem, here is a simple way to see what the "real" cost of `my_function` is:
+```
+  Timer t;
+  MPI_Barrier (MPI_COMM_WORLD);
+  t.start();
+  my_function();
+  MPI_Barrier (MPI_COMM_WORLD);
+  t.stop();
+  if (my MPI rank == 0)
+    std::cout << "Calling my_function() took " << timer() << " seconds." << std::endl;
+```
+
+This way, you really only measure the time spent between when all processors have finished doing what they were doing before, and when they are all finished doing what they needed to do for `my_function`.
+
+Another way to find some answers is to use the capabilities of the `Timer` class which can provide more detailed information when deal.II is configured to support MPI.
+
+# I have a special kind of equation!
+
+## Where do I start?
+
+The deal.II tutorial has a number of programs that deal with particular kinds of equations, such as vector-valued problems, mixed discretizations, nonlinear and time-dependent problems, etc. The best way to start is to take a look at the existing tutorial programs and see if there is one that is already close to what you want to do. Then take that, try to understand its structure, and find a way to modify it to solve your problem as well. Most applications written based on deal.II are not written entirely from scratch, but have started out as modified tutorial programs.
+
+## Can I solve my particular problem?
+
+The simple answer is: if it can be written as a PDE, then this is possible as evidenced by the many publications in widely disparate fields obtained with the help of deal.II. The more complicated answer is: deal.II is not a problem-solving environment, it is a toolbox that supports you in solving a PDE by the method of finite elements. You will have to implement assembling matrices and right hand side vectors yourself, as well as nonlinear outer iterations, etc. However, you will not need to care about programming a triangulation class that can handle locally refined grids in one, two, and three dimensions, linear algebra classes, linear solvers, different finite element classes, etc.
+
+To give only a very brief overview of what is possible, here is a list of the nontrivial problems that were treated by the programs that the main authors alone wrote to date:
+
+ - Time-dependent acoustic and elastic wave equation, including nonlocal absorbing boundary conditions;
+ - Stokes flow discretized with the discontinuous Galerkin finite element method;
+ - General hyperbolic problems including Euler flow, using the discontinuous Galerkin finite element method;
+ - Distributed parameter estimation problems;
+ - Mixed finite element discretization of a mortar multiblock formulation of the Laplace equation;
+ - Large-deformation elasto-plasticity in the simulation of plate tectonics.
+
+To illustrate the complexity of the programs mentioned above we note that most of them include adaptive mesh refinement tailored to the efficient computation of specific quantities of physical interest and error estimation measured in terms of these quantities. This includes the solution of a so-called dual problems, that means e.g. for the wave equation the solution of a wave equation solved backward in time.
+
+Problems other users of deal.II have solved include:
+ - Elastoplasticity;
+ - Porous media flow;
+ - Crystal growth simulations;
+ - Fuel cell simulations and optimization;
+ - Fluid-structure interaction problems;
+ - Time dependent large deformation problems for metal forming;
+ - Contact problems;
+ - Viscoelastic deformation of continental plates;
+ - Glacial ice flows;
+ - Thermoelastoplastic metal forming;
+ - Eulerian coordinates problems in biomechanical modeling.
+
+Some images from these applications can be found on the deal.II Wiki's [page. A good overview of the sort of problems that are being solved with the help of deal.II can also be obtained by looking at the large number of
+[http://www.dealii.org/developer/publications/toc.html publications written with the help of deal.II]([[Gallery]]]).
+
+Probably, many other problem types are solved by the many users which we do not know of directly. If someone would like to have his project added to this page, just contact us.
+
+
+## Why use deal.II instead of writing my application from scratch?
+
+You can usually get the initial version of a code for any given problem done relatively quickly when you write it yourself, since the learning curve is not as steep as if you had to learn a new library; it's also true that it's easy to make this code twice as fast as if you had to use a library. In other words, this sounds like you should write finite element codes for your problem yourself.
+
+However, you also need to keep in mind that it is the things you want to do after the first 3 months that will take you forever if you want to write it yourself, and where you will never be able to catch up with existing, established libraries: higher order elements; complicated, unstructured 3d meshes; parallelization; producing output in a format that's easily visualizable in 3d; adding an advected field for a tracer quantity; etc. Viewed this way, it's worth remembering that the primary commodity that's in short supply is not CPU time but your own programming time, and that's where you will be '''orders magnitude faster''' when using what others have already done, even if maybe your program ends up twice as slow as if you had written it from scratch with a particular application in mind.
+
+## Can I solve problems over complex numbers?
+
+Yes, you can, and it has been done numerous times with deal.II. However, we have a standard recommendation: consider such problems as systems of partial differential equations, where the individual components of the solution are the real and imaginary part of your unknown. The reason for this is that for complex-valued problems, the product <u,v> of two vectors is not the same as <v,u>, and it is very easy to get this wrong in many places. If you want to avoid these common traps, then the easiest way around is to split up you equation into two equations of real and imaginary part first, and then treat the resulting system as a system of real variables. This also makes the type of linear system clearer that you get after discretization, and tells you something about which solver may be adequate for it.
+
+The step-29 tutorial program shows how this is done for a complex-valued Helmholtz problem.
+
+## How can I solve a problem with a system of PDEs instead of a single equation?
+
+The easiest way to do this is setting up a system finite element after you chose your base element, e.g.,
+```
+FE_Q<dim> base_element(2);
+FESystem<dim> system_element(base_element, 3);
+```
+
+will produce a biquadratic element for a system of 3 equations. With this finite element, all the functions that you always called for a scalar finite element should just work for this vector-valued element as well.
+
+Refer to the step-8 and in particular to the step-20 tutorial programs for a lot more information on this topic. Several of the other tutorial programs beyond step-20 also use vector-valued elements and there is a whole module in the documentation on vector-valued problems that is worth reading.
+
+## Is it possible to use different models/equations on different parts of the domain?
+
+Yes. The step-46 tutorial program shows how to do this: It solves a problem in which we solve Stokes flow in one part of the domain, and elasticity in the rest of the domain, and couple them on the interface. Similar techniques can be used if you want to exclude part of the domain from consideration, for example when considering voids in a body in which the governing equations do not make sense because there is no medium.
+
+## Where do I start to implement a new Finite Element Class?
+
+If you really need an element that isn't already implemented in deal.II, then you'll have to understand the interplay between FEValues, the finite element, the mapping, and quadrature objects. A good place to start would be to read the deal.II paper (Bangerth, Hartmann, Kanschat, ACM Trans. Math. Softw., 2007).
+
+The actual implementation would most conveniently start from the
+`FE_Poly` class. You first implement the
+necessary polynomial space in the base library, then you derive
+`FE_Your_FE_Name` from `FE_Poly` (using your new polynomial class as a template)
+and add the connectivity information.
+
+You'll probably need more specific help at various points -- this is what the mailing list is there for!
+
+# General finite element questions
+
+## How do I compute the error
+
+If your goal is to compute the error in the form `||`u-u<sub>h</sub>`||` in some kind of
+norm, then you should use the function {{{VectorTools::integrate_difference}}}
+which can compute the norm above in any number of norms (such as the L2, H1,
+etc., norms). Take a look at step-7.
+
+On the other hand, if your goal is to *estimate* the error, then the one class
+that can do this is {{{KellyErrorEstimator}}}. This class is used in most of the
+tutorial programs that use adaptively refined meshes, starting with step-6.
+
+## How to plot the error as a pointwise function
+
+The functions mentioned in the previous question compute the error as a
+cellwise value. As a consequence, the values computed also include a factor
+that results from the size of the cell. If you're interested in the pointwise
+error as something that can be visualized, for example because you want to
+find a pattern in why the solution is not as you expect it to be, what you
+should do is this:
+ - Interpolate the exact solution
+ - Subtract the interpolated exact solution from the computed solution
+ - Put the resulting vector into a {{{DataOut}}} object. This will plot the nodal values of the errors u-u<sub>h</sub> on the current mesh.
+
+As an example, the following code shows how to do this in principle:
+```
+  template <int dim>
+  class ExactSolution : public Function<dim>
+  {
+  public:
+    ExactSolution () : Function<dim>(dim+1) {}
+
+    virtual double value (const Point<dim>   &p,
+                          const unsigned int  component) const
+    {
+      return ...exact solution as a function of p...
+    }
+  };
+
+
+  template <int dim>
+  void MyProblem<dim>::plot_error () const
+  {
+    Vector<double> interpolated_exact_solution (dof_handler.n_dofs());
+    VectorTools::interpolate (dof_handler,
+                              ExactSolution<dim>(),
+                              interpolated_exact_solution);
+    interpolated_exact_solution -= solution;
+
+    DataOut<dim> data_out;
+
+    data_out.attach_dof_handler (dof_handler);
+    data_out.add_data_vector (solution, "solution");
+    data_out.add_data_vector (interpolated_exact_solution, "pointwise_error");
+  }
+```
+
+
+## I'm trying to plot the right hand side vector but it doesn't seem to make sense!
+
+In particular, what you probably see is that the plot shows values that are
+smaller by a factor of two along the boundary than in the inside, and by a
+factor of four in the corners (in 2d) or eight (in 3d). Similarly, on
+adaptively refined cells, the values appear to scale with the cell size. The reason is that trying to plot a right hand side vector doesn't make sense.
+
+While you plot the vector as if it is function (by connecting dots with straight lines in 1d, or plotting surfaces in 2d), the thing you right hand side vector is in fact an element of the dual space. To wit:
+ - A vector in primal space is a vector of nodal values so that `sum_i  U_i phi_i(x)` is a reasonable function of `x`. Solution vectors are examples of elements of primal space.
+ - A vector in dual space is a vector W formed from the integration of an object in primal space against the shape functions, e.g. `W_i  = int f(x) phi_i(x)`. Examples of dual vectors are right hand side vectors.
+
+For vectors in dual space, it doesn't make sense to plot them as functions of the form
+     `sum_i W_i phi_i(x)`.
+The reason is that the values of the coefficients W_i are not of **amplitude** kind. Rather, the W_i are of kind amplitude (e.g. f(x)) times integration volume (the integral `*` dx over the support of shape functions phi_i). In other words, the sizes of cells comes into play for W_i, as does whether a shape function lies in the interior or at the boundary. In your case, the area of the integral when you integrate against shape functions at the boundary happens to be half the size of the integration area for shape functions in the interior.
+
+
+## What does XXX mean?
+
+The documentation of deal.II uses many finite element specific terms that may not always be entirely clear to someone not familiar with this language. In addition, we have certainly also invented our shares of deal.II specific terminology. If you encounter something you are not familiar with, take a look at the [deal.II glossary page](http://www.dealii.org/developer/doxygen/deal.II/DEALGlossary.html) that explains many of them.
+
+# I want to contribute to the development of deal.II!
+
+deal.II is Open Source -- this not only implies that you as everyone else has
+access to the source codes, it also implies a certain development model:
+whoever would like to contribute to the further development is invited to do
+so: If you have changes or ideas, please send them to the
+[deal.II mailing list](http://www.dealii.org/mail.html)!
+
+This model follows a small number of simple rules. The first and basic one is that if you have something that might be of interest to others as well, you are invited to send it to the list for possible inclusion into the library and use by others as well. Such additions useful to others are, for example:
+ - new backends for output in a new graphical format;
+ - input filters for some kind of data;
+ - tool classes that do something that might be interesting to use in other programs as well.
+
+A few simple projects can also be found in the
+[list of open issues](https://code.google.com/p/dealii/issues/list), where they
+are generally marked as "Enhancements".
+
+If you consider providing some code for inclusing into the library, these are the simple rules of gaining reputation in the Open Source community:
+ - your reputation grows with the number and complexity of your contributions;
+ - your reputation with the maintainers of the library also grows with the degree of conformance of your proposed additions with the administrative rules stated below;
+ - originators of code are credited full authorship.
+
+In order to allow that a library remains a consistent piece of software, there are a number of administrative rules:
+ - there are a number of maintainers that decide what goes into the library;
+ - maintainers are benevolent, i.e. in general they want your addition to become part of the library;
+ - however, they have to evaluate additions with respect to some criteria, among which are value for others;
+ - whether it fits into the general framework (meaning that if your contribution requires the installation of some obscure other library that people do not usually have, then that must be discussed; alternatively, a way must be provided to disable your contribution on machines that do not have this lib);
+ - completeness and amount of documentation;
+ - existence and completeness of error checking through assertions.
+
+However, again: the basic rule is that if you think your addition is interesting to others, there most probably is a way to get it into the library!
+
+
+# I found a typo or a bug and fixed it on my machine. How do I get it included in deal.II?
+
+First: thank you for wanting to do this! This software project is kept alive
+by people like you contributing to it. We like to include any improvement, even if it is just a single typo that you fixed.
+
+If you have only a small change, or if this is your first time submitting
+changes, the easiest way to get them to us is by just emailing the
+[deal.II mailing lists](http://dealii.org/mail.html) and we will make sure they
+get incorporated. If you continue submitting patches (which we hope you will!)
+and become more experienced, we will start to ask you to use
+[git](http://en.wikipedia.org/wiki/Git_%28software%29) as the version control
+system and base your patches off of the 
+[deal.II github repository](https://github.com/dealii/dealii).
+
+The process for this is essentially the following (if you don't quite
+understand the terminology below, take a look at the manuals at the
+[github web site](https://github.com/), read
+[this online tutorial](https://www.atlassian.com/git/tutorial), or ask on the
+mailing list):
+  - Create a github account
+  - Fork the deal.II github repository, using the button at the top right of https://github.com/dealii/dealii
+  - Clone the repository onto your local file system
+  - Create a branch for your changes
+  - Make your changes
+  - Push your changes to your github repository
+  - Create a pull request for your changes by going to your github account's deal.II tab where, after the previous step, there should be a button that allows you to create a pull request.
+
+This list may sound intimidating at first, but in reality it's a fairly
+straightforward process that takes no more than 2 minutes after the first
+couple of times. But, as said, we'll be happy to hold your hand the first few
+times around and help you with the process!
+
+If you've submitted patches several times and know your way around git by now,
+please also consider to
+  - make sure you base your patch off the most recent revision of the repository
+  - you rewrite the history of your patch so that it contains a relatively small number of commits that are each internally consistent and could also be applied independently (see, for example, [the discussion towards the bottom of this page](https://github.com/dealii/dealii/pull/87)).
+
+
+
+# I'm fluent in deal.II, are there jobs for me?
+
+Certainly. People with numerical skills are a sought commodity, both in academia and in businesses. In the US, the National Labs are also hiring lots of people in this field.
\ No newline at end of file
diff --git a/Function-Plotting-Tool.md b/Function-Plotting-Tool.md
new file mode 100644 (file)
index 0000000..00d68d8
--- /dev/null
@@ -0,0 +1,672 @@
+# A program to convert an analytically known function into a visualization
+
+<!-- No auto-Table of Contents support! -->
+
+## Introduction
+
+This is a little program that reads the formula of a function from an input file (along with other information) and generates a graphical representation of this function in one of the formats supported by the deal.II DataOutBase class for plotting in one of the widely used visualization programs.
+To use this program, you have to cut and paste the `plot.cc` and `Makefile` to a directory of your choice. 
+
+Change the Makefile to reflect your installation of deal.II. Then say
+```
+make
+```
+Run the executable (default is `plot`). This will create a file `parameters.par` that you can edit to change the function, change the output format, etc.
+
+
+If you call the executable with a command line option, e.g.
+```
+test@somewhere.com> ./plot myparameters.par
+
+0.0689890:DEAL:SetUpLogging::Log file output.log
+0.0709890:DEAL::Finite Element: FE_Q<2>(1)
+0.0709890:DEAL::Generated a 1 valued FunctionParser.
+0.0969850:DEAL:CreateMesh::Active Cells: 256
+0.0969850:DEAL:CreateMesh::Distributing DOFS
+0.263959:DEAL:cg::Starting value 0.0818334
+0.269958:DEAL:cg::Convergence step 18 value 3.86807e-17
+0.269958:DEAL:OutputSolution::Writing system solution: output.gmv
+```
+the program will read `myparameters.par` and write on whatever you specified in this file. 
+
+
+
+## The source file
+
+```
+//----------------------------  plot.cc  ---------------------------
+//
+//    Copyright (C) 2005 by Luca Heltai
+//
+//    This file is subject to QPL and may not be  distributed
+//    without copyright and license information. Please refer
+//    to the file deal.II/doc/license.html for the  text  and
+//    further information on this license.
+//
+//----------------------------  plot.cc  ---------------------------
+
+// Base libraries
+#include <base/function_parser.h>
+#include <base/parameter_handler.h>
+#include <base/logstream.h>
+#include <base/quadrature_lib.h>
+
+// Grid libraries
+#include <grid/tria.h>
+#include <grid/grid_in.h>
+#include <grid/grid_refinement.h>
+#include <grid/grid_generator.h>
+
+// Dofs libraries
+#include <dofs/dof_handler.h>
+#include <dofs/dof_constraints.h>
+
+// Finite Element libraries.
+#include <fe/fe_system.h>
+#include <fe/mapping_q.h>
+#include <fe/fe_tools.h>
+
+// Linear Algebra Class libraries.
+#include <lac/vector.h>
+
+// Numerics libraries
+#include <numerics/vectors.h>
+#include <numerics/data_out.h>
+
+// C++ libraries
+#include <fstream>
+
+
+#ifdef HAVE_STD_STRINGSTREAM
+#  include <sstream>
+#  define MY_STR str().c_str()
+#  define MY_OSTRSTREAM std::ostringstream
+#else
+#  include <strstream>
+#  define MY_STR str()
+#  define MY_OSTRSTREAM  std::ostrstream
+#endif
+class Parameters : public ParameterHandler
+{
+ public:
+  Parameters(int, char**);
+  ~Parameters();
+  
+  /** Reads the parameters. This method reads the input file
+      "parameters.par" and set all the variable of this class to
+      be used later in the problem. */
+  void set_parameters();
+  
+  /** Log file name. Used by the deallog class. */
+  std::string  log_file;
+  /** Verbosity of console logging. 0 disables it. */
+  unsigned int log_console_level;
+  /** Verbosity of file logging. 0 disables it. */
+  unsigned int log_file_level;
+  /** Write time information. Decides wether to write time information
+      in the log file. */
+  bool         log_record_time;
+  /** Use differential time when loggin.*/
+  bool         log_differential_time;  
+  
+  /** Read the domain mesh from a file. If set to false, the domain is
+      the hypercube [bool read_mesh_from_file;
+  
+  /** The global initial refinement.*/
+  unsigned int grid_refinement;
+
+  /** The Finite Element to use.*/
+  std::string    finite_element;
+  
+  /** The file to read. If there is a command line argument, this file
+      is read, if it is there, else it is filled with default
+      values.*/
+  std::string     file_parameters;
+
+  /** File of Solution.*/
+  std::string     file_solution;
+
+  /** Format of the solution. Supported formats:
+      dx|ucd|gmv|gpl|eps|pov|tec|tecbin|vtk*/
+  std::string     file_solution_format;
+
+  /** Input file for the domain mesh. Supported format: gmsh.*/
+  std::string    file_domain_mesh;
+
+  /** Variables to use in our function. This is the string that
+      contains the name of the variables used in the function to
+      plot. */
+  std::string   variables;
+  /** Expression of the function to plot. */
+  std::string   expression;
+  
+  /** Number of Quadrature points used to project. It has to be
+      enough.*/
+  unsigned int n_q_points;
+};
+  
+
+
+/** 
+   Output Object. This class is used for all output related things.
+*/
+template <int dim,
+         typename VECTOR=Vector<double> >
+class OutputObject
+{
+  public:
+  
+  OutputObject (Parameters * some_par) {
+    par = some_par;
+  };
+  /** Output system Solution. The output format is defined in
+      according to values set in "parameters.par". \see Parameters
+      for available options. */
+  void output_solution (const DoFHandler<dim> &dof_handler,
+                       const VECTOR &solution,
+                       unsigned int n_components);
+  
+  /** Setup Logging.*/
+  void set_log_file ();
+  
+  private:
+  /** 
+      Holds the problem parameters.
+  */
+  Parameters * par;
+  
+  /** Output File. */
+  std::ofstream log_file;
+};
+
+
+/**
+ - This class implements a drawer. We make use of a few classes from
+ - the deal.II library, to show how to output a given function
+ - interpolated on a given finite element space.
+ - @author Luca Heltai, 2005
+ */
+template <int dim, typename VECTOR=Vector<double> >
+class FunctionDraw {
+  public:
+  FunctionDraw(int, char**); 
+  ~FunctionDraw(); 
+    
+  void run();
+  
+  private:
+  void initialize();
+  void create_mesh();
+  void output_function();
+  
+  Parameters par;
+
+  Triangulation<dim> triangulation;
+   
+  DoFHandler<dim> dof_handler;
+  
+  OutputObject<dim> out;
+  
+  VECTOR solution;
+
+  SmartPointer<FiniteElement<dim> > fe;
+  
+  SmartPointer<FunctionParser<dim> > function;
+  
+};
+    
+/** The initialization of the parameters follows the general structure of the
+    \class ParameterHandler, with structured input.
+*/
+Parameters::Parameters(int argc, char ** argv) 
+{
+  enter_subsection ("Logging");
+  
+  declare_entry("Log file", "output.log", Patterns::Anything());
+  declare_entry("Log console level", "5", Patterns::Integer());
+  declare_entry("Log file level", "3", Patterns::Integer());
+  declare_entry("Write time information", "true", Patterns::Bool());
+  declare_entry("Use differential time", "false", Patterns::Bool());
+  
+  leave_subsection();
+  
+  enter_subsection ("I/O Options");
+
+  declare_entry("Write parameter file", "true", Patterns::Bool());
+  declare_entry("Parameter file", "parameters.par", Patterns::Anything());
+
+  declare_entry("Solution file", "output",  Patterns::Anything());
+  declare_entry("Solution format", "gmv",  
+               Patterns::Selection("dx|ucd|gmv|gpl|eps|pov|tec|tecbin|vtk"));
+  declare_entry("Read domain mesh from file", "false", Patterns::Bool());
+  declare_entry("Domain coarse mesh gmsh file", "square.msh",
+               Patterns::Anything()); 
+
+  leave_subsection();
+  
+  enter_subsection("Numerical Parameters");
+  declare_entry("Refinement", "4", Patterns::Integer());
+  declare_entry ("Finite element", "FE_Q(1)", Patterns::Anything());
+  declare_entry ("Number of quadrature points", "5", Patterns::Integer());
+  leave_subsection();
+  enter_subsection ("Problem Data");
+  declare_entry ("Variables", "x,y", Patterns::Anything());
+  declare_entry ("Function to plot", "0", Patterns::Anything());
+  leave_subsection ();
+  
+  if(argc > 1) 
+    file_parameters = argv[1](0,1]^dim.*/);
+  else 
+    file_parameters = "parameters.par";
+}
+
+Parameters::~Parameters() 
+{}
+
+void Parameters::set_parameters ()
+{
+  read_input(file_parameters);
+  
+  enter_subsection ("Logging");
+  
+  log_file             = get("Log file");
+  log_console_level    = get_integer("Log console level");
+  log_file_level       = get_integer("Log file level");
+  log_record_time      = get_bool("Write time information");
+  log_differential_time        = get_bool("Use differential time");
+  
+  leave_subsection();
+  
+  enter_subsection ("I/O Options");
+  
+
+  file_parameters      = get ("Parameter file");
+
+  file_solution                = get ("Solution file");
+  file_solution_format = get ("Solution format");
+
+  read_mesh_from_file  = get_bool("Read domain mesh from file");
+  file_domain_mesh     = get ("Domain coarse mesh gmsh file");
+
+  leave_subsection();
+  
+  enter_subsection ("Numerical Parameters");
+  grid_refinement      = get_integer ("Refinement");  
+  finite_element       = get("Finite element");
+  n_q_points           = get_integer("Number of quadrature points");
+  
+  leave_subsection();
+  
+  enter_subsection ("Problem Data");
+  variables = get("Variables");
+  expression = get("Function to plot");
+  leave_subsection ();
+  
+  std::ofstream out (file_parameters.c_str());
+  print_parameters(out, Text);
+  
+}
+
+template <int dim, typename VECTOR>
+void OutputObject<dim,VECTOR>::set_log_file () {
+   // Initialize Logging to output file.
+  log_file.open(par->log_file.c_str());
+  deallog.attach(log_file);
+  deallog.depth_console(par->log_console_level);
+  deallog.depth_file(par->log_file_level);
+  deallog.log_execution_time (par->log_record_time);
+  deallog.log_time_differences (par->log_differential_time);
+  deallog.push("SetUpLogging");
+  deallog << "Log file " 
+         << par->log_file << std::endl;
+  deallog.pop();
+}
+
+template <int dim, typename VECTOR>
+void OutputObject<dim,VECTOR>::output_solution(const DoFHandler<dim> &dof_handler,
+                                              const VECTOR &solution,
+                                              unsigned int n_components)
+{
+  deallog.push("OutputSolution");
+  
+  char   filename[sprintf(filename,"%s.%s", par->file_solution.c_str(),
+         par->file_solution_format.c_str());
+    
+  deallog << "Writing system solution: " << filename 
+         << std::endl;
+    
+    
+  std::ofstream output (filename );
+    
+  DataOut<dim> data_out;
+    
+  std::vector<std::string> solution_names; 
+  
+  for (unsigned int i=1; i<= n_components; ++i) {
+    MY_OSTRSTREAM tmp;
+    tmp << "v_" << i;
+    solution_names.push_back( tmp.MY_STR );
+  }                                                            
+  
+  data_out.attach_dof_handler (dof_handler);
+  data_out.add_data_vector (solution, solution_names);
+    
+  data_out.build_patches (1);
+  if (par->file_solution_format == "dx") data_out.write_dx (output);
+  else if (par->file_solution_format == "ucd" ) data_out.write_ucd (output);
+  else if (par->file_solution_format == "gpl" ) data_out.write_gnuplot (output);
+  else if (par->file_solution_format == "eps" ) data_out.write_eps (output);
+  else if (par->file_solution_format == "pov" ) data_out.write_povray (output);
+  else if (par->file_solution_format == "tec" ) data_out.write_tecplot (output);
+  else if (par->file_solution_format == "tecbin" ) data_out.write_tecplot_binary (output);
+  else if (par->file_solution_format == "vtk" ) data_out.write_vtk (output);
+  else if (par->file_solution_format == "gmv" ) data_out.write_gmv (output);
+  else {
+    Assert(false, ExcInternalError());
+  }
+  deallog.pop();
+}
+
+template <int dim, typename VECTOR>
+FunctionDraw<dim,VECTOR>::FunctionDraw(int argc, char ** argv) :
+  par(argc, argv),
+  dof_handler(triangulation),
+  out(&par)
+{}
+
+template <int dim, typename VECTOR>
+FunctionDraw<dim,VECTOR>::~FunctionDraw() 
+{
+  dof_handler.clear();
+
+  FunctionParser<dim> * function_real = function;
+  function = 0;
+  delete function_real;
+  
+  FiniteElement<dim> * fe_real = fe;
+  fe = 0;
+  delete fe_real;
+}
+
+
+template <int dim, typename VECTOR>
+void FunctionDraw<dim,VECTOR>::initialize()
+{
+  par.set_parameters();
+  out.set_log_file();
+  
+  // Creates a new pointer to a FESystem
+  FiniteElement<dim> *fe_real = 
+    FETools::get_fe_from_name<dim>(par.finite_element);
+  // Associates a smart pointer to the newly created pointer.
+  fe = fe_real;
+  
+  deallog << "Finite Element: " << fe->get_name() << std::endl;
+  // generate a new function parser
+  FunctionParser<dim> * function_real = 
+    new FunctionParser<dim>(fe->n_components());
+  // assign it to our function
+  function = function_real;
+  
+  deallog << "Generated a " << fe->n_components() 
+         << " valued FunctionParser." << std::endl;
+    
+  
+  // Constants we want to pass to the function parser
+  std::map<std::string, double> constants;
+  constants["pi"](100];) = M_PI;
+  
+  function->initialize(par.variables,
+                      par.expression,
+                      constants);
+  
+}
+
+template <int dim, typename VECTOR>
+void FunctionDraw<dim,VECTOR>::run()
+{
+  initialize();
+  
+  create_mesh();
+
+  output_function();
+}
+
+template <int dim, typename VECTOR>
+void FunctionDraw<dim,VECTOR>::create_mesh()
+{
+  deallog.push("CreateMesh");
+  
+  if(par.read_mesh_from_file) {
+    GridIn<dim> grid_in;
+    grid_in.attach_triangulation (triangulation);
+    std::ifstream input_file(par.file_domain_mesh.c_str()); 
+    grid_in.read_msh(input_file); 
+  } else {
+    GridGenerator::hyper_cube (triangulation, 0, 1);
+  }
+  
+  triangulation.refine_global (par.grid_refinement);
+  
+  deallog << "Active Cells: "
+         << triangulation.n_active_cells()
+         << std::endl;
+  
+  deallog << "Distributing DOFS" << std::endl;
+  
+  dof_handler.distribute_dofs (*fe);
+  solution.reinit(dof_handler.n_dofs());
+  
+  deallog.pop();
+}
+
+template <int dim, typename VECTOR>
+void FunctionDraw<dim,VECTOR>::output_function()
+{
+  QGauss< dim > quadrature(par.n_q_points);
+  ConstraintMatrix constraints;
+  constraints.close();
+  MappingQ<dim> mapping(1);
+  
+  VectorTools::project(mapping,
+                      dof_handler,
+                      constraints,
+                      quadrature,
+                      *function,
+                      solution);
+
+  out.output_solution(dof_handler,
+                     solution,
+                     fe->n_components() );
+  
+}
+
+int main (int argc, char ** argv)
+{
+  try
+    {  
+      FunctionDraw<2> draw(argc, argv);
+      draw.run();
+    }
+  catch (std::exception &exc)
+    {
+      std::cerr << std::endl << std::endl
+                << "----------------------------------------------------"
+                << std::endl;
+      std::cerr << "Exception on processing: " << std::endl
+                << exc.what() << std::endl
+                << "Aborting!" << std::endl
+                << "----------------------------------------------------"
+                << std::endl;
+      return 1;
+    }
+  catch (...)
+    {
+      std::cerr << std::endl << std::endl
+                << "----------------------------------------------------"
+                << std::endl;
+      std::cerr << "Unknown exception!" << std::endl
+               << "Aborting!" << std::endl
+                << "----------------------------------------------------"
+                << std::endl;
+      return 1;
+    };
+  return 0;
+}                                
+```
+
+
+## The Makefile
+
+```
+
+target = plot
+
+debug-mode = on
+
+
+D = /usr/local/deal.II
+
+
+clean-up-files = *gmv *gnuplot *gpl *eps **pov
+
+
+
+
+include $D/common/Make.global_options
+
+
+libs.g   = $(lib-deal2-2d.g) \
+           $(lib-lac.g)      \
+           $(lib-base.g)
+libs.o   = $(lib-deal2-2d.o) \
+           $(lib-lac.o)      \
+           $(lib-base.o)
+
+
+ifeq ($(debug-mode),on)
+  libraries = $(target).g.$(OBJEXT) $(libs.g)
+else
+  libraries = $(target).$(OBJEXT) $(libs.o)
+endif
+
+
+$(target) : $(libraries)
+        @echo ============================ Linking $@
+        @$(CXX) -o $@$(EXEEXT) $^ $(LIBS) $(LDFLAGS)
+
+
+run: $(target)
+        @echo ============================ Running $<
+        @./$(target)$(EXEEXT)
+
+
+clean:
+        -rm -f **.$(OBJEXT) **~ Makefile.dep $(target)$(EXEEXT) $(clean-up-files)
+
+
+./%.g.$(OBJEXT) :
+        @echo ==============debug========= $(<F)
+        @$(CXX) $(CXXFLAGS.g) -c $< -o $@
+./%.$(OBJEXT) :
+        @echo ==============optimized===== $(<F)
+        @$(CXX) $(CXXFLAGS.o) -c $< -o $@
+
+
+.PHONY: run clean
+
+
+Makefile.dep: $(target).cc Makefile \
+              $(shell echo $D/**/include/**/**.h)
+        @echo ============================ Remaking $@
+        @$D/common/scripts/make_dependencies  $(INCLUDE) -B. $(target).cc \
+                > Makefile.dep
+        @if test -s $@ ; then : else rm $@ ; fi
+
+
+include Makefile.dep
+
+```
+
+
+## An example parameter file
+
+```
+# Listing of Parameters
+# ---------------------
+subsection I/O Options
+  set Domain coarse mesh gmsh file = square.msh
+  set Parameter file               = parameters.par
+  set Read domain mesh from file   = false
+  set Solution file                = output
+  set Solution format              = gmv
+  set Write parameter file         = true
+end
+
+
+subsection Logging
+  set Log console level      = 5
+  set Log file               = output.log
+  set Log file level         = 3
+  set Use differential time  = false
+  set Write time information = true
+end
+
+
+subsection Numerical Parameters
+  set Finite element              = FE_Q(1)
+  set Number of quadrature points = 5
+  set Refinement                  = 4
+end
+
+
+subsection Problem Data
+  set Function to plot = exp(x*y) # default: 0
+  set Variables        = x,y
+end
+</pre>
+
+## Another example parameter file
+
+<pre>
+# Listing of Parameters
+# ---------------------
+subsection I/O Options
+  set Domain coarse mesh gmsh file = square.msh
+  set Parameter file               = parameters.par
+  set Read domain mesh from file   = false
+  set Solution file                = output
+  set Solution format              = gmv
+  set Write parameter file         = true
+end
+
+
+subsection Logging
+  set Log console level      = 5
+  set Log file               = output.log
+  set Log file level         = 3
+  set Use differential time  = false
+  set Write time information = true
+end
+
+
+subsection Numerical Parameters
+  set Finite element              = FESystem[set Number of quadrature points = 5
+  set Refinement                  = 4
+end
+
+
+subsection Problem Data
+  set Function to plot = sin(pi*y);sin(pi*x) # default: 0
+  set Variables        = x,y
+end
+```
+
+--[[User:Luca|Luca]](FE_Q(1)^2]) 08:39, 5 Apr 2005 (CEST)
\ No newline at end of file
diff --git a/Gallery.md b/Gallery.md
new file mode 100644 (file)
index 0000000..990bd40
--- /dev/null
@@ -0,0 +1,289 @@
+# A gallery of nice pictures generated by deal.II
+
+**Table of contents:**
+<wiki:toc />
+
+This page is essentially a collection of images put here for purely esthetic reasons, and a little bit in order to
+show what can be done with deal.II. Most of the pictures also contain a brief summary of what they show, in order
+to give an idea of the kind of problem they are meant to solve.
+
+Feel free to add your own pictures here, but please add the name of the person who did the simulation -- others may be so excited by it that they would want to contact you!
+
+
+## Flow through the blades of a turbine
+
+<img width="400px" src="http://www.dealii.org/images/wiki/gallery/turbine.png" />
+
+High-Reynolds number
+computations lead to instationary solutions that are, however, often
+enormously important in practice. This picture is by Manuel Quezada de
+Luna (Texas A&M University) and was taken from a simulation of flow
+between the blades of a compressor or turbine.
+
+
+## Complex geometries
+
+<img width="400px" src="http://www.dealii.org/images/wiki/gallery/yuhan-1.png" />
+<img width="400px" src="http://www.dealii.org/images/wiki/gallery/yuhan-2.png" />
+
+These pictures are from a semester project by Yuhan Zhou at Texas A&M
+University. The goal was to compute parasitic conducivities and impedances
+from multilayer chip layouts. Other than generating data, this project also
+produced a number of pretty pictures!
+
+
+
+## Thermally driven convection
+
+<table>
+  <tr><td><img width="400px" src="http://www.dealii.org/images/wiki/gallery/Step-22.candles-1.png" /></td><td><img width="400px" src="http://www.dealii.org/images/wiki/gallery/Step-22.candles-2.png" /></td></tr>
+</table>
+
+The images on the left show results obtained with a variant of the step-22 [tutorial program that computes thermally driven convection with Stokes flow. The images show three non-equidistantly space heat sources at the bottom and the flow field that emanates at various times from the rising plumes of hot air.
+
+The flow pattern becomes unstable at various times switching from one configuration to another. The full dynamics only really become visible when watching these images as a movie.
+Several movies of various configurations are posted on Wolfgang Bangerth's webpage [http://www.math.tamu.edu/~bangerth/pictures.html#convection](http://dealii.org/developer/doxygen/deal.II/step_22.html]).
+
+
+(Origin: Wolfgang Bangerth, December 2007)
+
+
+
+## Optical imaging
+
+<table>
+  <tr><td><img width="400px" src="http://www.dealii.org/images/wiki/gallery/Tumor-1.png" /></td><td><img width="400px" src="http://www.dealii.org/images/wiki/gallery/Tumor-4.png" /></td></tr>
+</table>
+
+These are a couple of pictures created for an application in biomedical imaging. The exact meaning of the various quantities shown are explained in more detail at this linke [In short, the iso-contours on the left show the intensity of incident and fluorescent light, whereas the volume image on the right depicts the reconstructed tumor location.
+
+(Origin: Wolfgang Bangerth, December 2007)
+
+
+## Singular and Hypersingular Source Terms
+
+<table>
+  <tr><td><img width="400px" src="http://www.dealii.org/images/wiki/gallery/Single_layer.jpeg" /></td><td><img width="400px" src="http://www.dealii.org/images/wiki/gallery/Double_layer.jpeg" /></td></tr>
+</table>
+
+These images show a Laplacian with singular and hypersingular right hand sides, supported on a
+co-dimension one circle.
+
+(Origin: Luca Heltai, 16 May 2007)
+
+
+## Topology Optimization
+
+<img width="400px" src="http://www.dealii.org/images/wiki/gallery/Topopt1.png" />
+
+These images result from a constrained topology optimization problem related to the minimization of steady state thermal compliance on a 2D square plate. The optimization is performed on a hierarchically adapted grid:
+After completing optimization on a coarse grid level, the grid is adapted based on topology indicator derivatives and the optimization loop is restarted with interpolated topology indicator field on the (adaptively) refined grid as initial guess. The figure shows the global optimized topology and a selected zoomed part.
+
+(Origin: Rohallah Tavakoli, 9 Feb. 2007)
+
+
+## Multiphase flow
+
+<img width="200px" src="http://www.dealii.org/images/wiki/gallery/Random2d.png" />
+<img width="200px" src="http://www.dealii.org/images/wiki/gallery/Random3d.png" />
+
+These images show the saturation at one time step of a simulation of how a mixture of two fluids moves through a random medium in 2d (left) and 3d (right). The full description as well as movies of this problem can be found as step-21 in the tutorial of deal.II.
+
+(Origin: Wolfgang Bangerth, 2006)
+
+
+## Phase change/crystal growth
+
+<img width="200px" src="http://www.dealii.org/images/wiki/gallery/Gallery-dendrite1.jpg" />
+<img width="200px" src="http://www.dealii.org/images/wiki/gallery/Gallery-dendrite2.jpg" />
+<img width="200px" src="http://www.dealii.org/images/wiki/gallery/Gallery-dendrite3.jpg" />
+
+Dendritic growth of crystals. (Origin: Denis Danilov)
+
+
+<img width="400px" src="http://www.dealii.org/images/wiki/gallery/Gallery-Grain_growth.png" />
+
+Phase field modeling of the normal grain growth.
+
+-Slawa, 07:49, 6 September 2010 (UTC)
+
+
+
+
+## Wave equations
+
+<img width="200px" src="http://www.dealii.org/images/wiki/gallery/Gallery-elasto_1x.png" />
+<img width="200px" src="http://www.dealii.org/images/wiki/gallery/Gallery-elasto_2x.png" />
+
+Here are two images of elastic waves propagating outward from their origin. One can think of this simulation as a two-dimensional solid where we tuck at the center, pull it to the right, then let it snap. What you get is a fast pressure (P-)wave travelling to the left and right, and aslower shear (S-)wave travelling up and downward. After a while, these waves hit the boundary of the domain and are reflected from there. A closer look at the data would reveal that the reflections bring conversions from P- to S-waves with them, but that would require taking a look at the curl and divergence of the vector fields separately. (Origin: Wolfgang Bangerth, 1999)
+
+<img width="200px" src="http://www.dealii.org/images/wiki/gallery/Gallery-acoustic_ring1.png" />
+
+This image shows waves in an inhomogenous medium after circling around the ring-shaped domain several times. Such waves
+occur in earthquake simulations, where shear waves only propagate in the the (solid) earth crust, but not in the (liquid)
+earth mantle and core below the crust. For strong earthquakes, these waves can travel around the entire globe several times before the are too attenuated to be detected. The resolution of this simulation is not high enough to be realistic, and neither are the geometry, dimensions, or physical constants realistic, but it gives an idea. (Origin: Wolfgang Bangerth, 1999)
+
+
+## Incompressible Navier-Stokes
+
+<img width="100px" src="http://www.dealii.org/images/wiki/gallery/Kovasznay10.jpg" />
+
+Visualization of the analytic solution to the Navier-Stokes equations by L. I. G. Kovasznay (Laminar flow behind a two-dimensional grid, Proc. Camb. Philos. Soc. 44, pp. 58-62, 1948). Displayed is the stationary concentration of a tracer entering from the left. Therefore, the lines of same color are stream lines. The nice thing about this solution is its existence for any Reynolds number (even if the stationary solution shown here may be unstable and therefore unphysical for higher Reynolds numbers).
+
+<img width="200px" src="http://www.dealii.org/images/wiki/gallery/Gallery-block10.jpg" />
+
+Here, Couette flow coming in from the far end of the brick flows around a cube standing on the ground. Imagine a very slow wind flow around a house. Reynolds number is 10 on the left and 100 on the right. You clearly see the wake behind the cube extending. Does anybody know if there is a loop in the wake? I could not find it putting in streamlines. Guido Kanschat 19:01, 17 May 2005 (CEST)
+<img width="200px" src="http://www.dealii.org/images/wiki/gallery/Gallery-block100.jpg" />
+
+
+<img width="250px" src="http://www.dealii.org/images/wiki/gallery/Gallery-backward_facing_step_01.jpg" />
+
+The pressure of an incompressible flow around a backward facing step is visualized. The Reynolds number is 50. The question is, if the positive singularity (the left one, on the inflow side) is a real physical phenomenon. Indeed, it is numerically stable. (Andre Große-Wöhrmann, 2005)
+
+
+## Convection in the earth core
+
+<img width="200px" src="http://www.dealii.org/images/wiki/gallery/Gallery-convection.png" />
+
+Convection in itself is a hard problem (see the entry further up this page on thermally driven convection]](http://www.math.tamu.edu/~bangerth/pictures.html#optical].), but if it is between moving surfaces or with nonvertical gravity, it is even more challenging. This is what makes simulations of the earth's interior, both of the liquid rock earth mantle as well of the liquid metal outer core, so complicated. The picture to the right shows streamlines of a simulation of a convecting fluid in a radial gravity field between a hotter inner sphere and a cooler outer sphere, both of which are rotating and dragging the fluid along. Under such conditions, very complicated flow patterns develop after a while - among which are those that are responsible for the earth's magnetic field. (Origin: Andre Grosse-Woehrmann, 2005)
+
+
+## Solitons
+
+The step-25 tutorial program demonstrates the solution of the nonlinear, wave equation-type sine-Gordon equation, from which the pictures at the right are taken. Full movies of these solutions can be found in the results section of that program as well.
+
+(Origin: Ivan Christov, 2006)
+
+<img width="180px" src="http://www.dealii.org/images/wiki/gallery/Gallery-step25-1.png" />
+<img width="180px" src="http://www.dealii.org/images/wiki/gallery/Gallery-step25-2.png" />
+<img width="180px" src="http://www.dealii.org/images/wiki/gallery/Gallery-step25-3.png" />
+
+
+## Transport
+
+<img width="200px" src="http://www.dealii.org/images/wiki/gallery/Gallery-transport_01.jpg" />
+
+Modelling transport via the wavelike approach, numerical waves occur.
+(Origin: Andre Große-Wöhrmann, 2005)
+
+<img width="200px" src="http://www.dealii.org/images/wiki/gallery/advdiff.jpg" />
+
+The rotating cone problem with some diffusion on a spacetime mesh
+(Origin: Guido Kanschat, 2007)
+
+
+<img width="200px" src="http://www.dealii.org/images/wiki/gallery/Gallery-kpp.png" />
+
+Modeling nonlinear transport equations is slightly more complicated since they can develop shocks even if the initial conditions are smooth. This isn't the case for the initial conditions that produced this solution of the KPP equations, but the difficulty of capturing the solution's features is still apparent.
+(Origin: Orhan Mamedov, Vladimir Tomov, Abner Salgado, as part of a student project, 2011)
+
+
+## Fictitious Domain Method
+
+<img width="200px" src="http://www.dealii.org/images/wiki/gallery/Gallery-fdm_stokes_01.jpg" />
+
+This is the boundary supported fictitious domain method applied for the problem of Stokes.`You can see the pressure and the velocity field. The velocity is enforced on the circle via a weak condition. The key feature of this method is that this curve may be independent of the discretization mesh. (Origin: Andre Große-Wöhrmann, 2005)
+
+<img width="200px" src="http://www.dealii.org/images/wiki/gallery/Gallery-fdm_potential_01.jpg" />
+
+This is the boundary supported fictitious domain method applied to the potential equation. Again the curve may be independent of the mesh. Nevertheless the mesh is refined in the vicinity of the curve. (Origin: Andre Große-Wöhrmann, 2005)
+
+
+## Immersed Boundary Method
+
+<img width="200px" src="http://www.dealii.org/images/wiki/gallery/shell_re10_0001.jpeg" />
+
+This is a messy representation of the hydrostatic pressure of a
+fluid-structure interaction system composed of an elastic shell
+immersed in an incompressible fluid. The simulation was done using the
+immersed boundary method and a "net-like" elasticity which results in
+the interior pressure of the shell being a mess.  --Luca Heltai 19:02, 17 January 2006 (CET)
+
+
+
+## Plastic and quasistatic deformation
+
+<img width="400px" src="http://www.dealii.org/images/wiki/step-42.displacement.png" />
+
+Deformation can be described in many ways. step-42 is a tutorial program
+(written by Joerg Frohne, 2013) that deals with plasticity and the picture above
+shows the displacement by pressing a printing letter in the shape of the
+Chinese character for "force" into a metal block. (The displacement at every
+node is exaggerated by a factor of 100.)
+
+On the other hand, the images below correspond to the step-18 tutorial program. It shows the gradual deformation of a cylinder under
+pressure from above, until it essentially fails. The color coding indicates
+stress levels in the material. Because it looks nice, at the very bottom, there is also an isosurface view of the x-displacement early on in the simulation. More details
+about this simulation can be found in the step-18
+tutorial. (Origin: Wolfgang Bangerth, 2005)
+
+
+<img width="200px" src="http://www.dealii.org/images/wiki/gallery/Solution-0002.0000.png" />
+<img width="200px" src="http://www.dealii.org/images/wiki/gallery/Solution-0005.0000.png" />
+<img width="200px" src="http://www.dealii.org/images/wiki/gallery/Solution-0007.0000.png" />
+
+<img width="200px" src="http://www.dealii.org/images/wiki/gallery/Solution-0008.0000.png" />
+<img width="200px" src="http://www.dealii.org/images/wiki/gallery/Solution-0009.0000.png" />
+<img width="200px" src="http://www.dealii.org/images/wiki/gallery/Solution-0010.0000.png" />
+
+
+<img width="300px" src="http://www.dealii.org/images/wiki/gallery/Step-18-contours.png" />
+
+
+
+## Complicated domains
+
+Here is an image of a mesh of a rather complicated domain. It shows a mesh created from CT data of the left lung (Origin: Li Pan, 2006)
+
+<img width="300px" src="http://www.dealii.org/images/wiki/gallery/Left_lung.png" />
+
+
+## Euler flow
+
+Euler flow; simulating a dense blob sliding downhill.  Using DG and a Lax-Friedrichs type flux; Full Newton solve of the nonlinear system, using Trilinos/Aztec solvers.  (Origin: David Neckels 2007)
+
+<img width="180px" src="http://www.dealii.org/images/wiki/gallery/euler1.jpg" />
+<img width="180px" src="http://www.dealii.org/images/wiki/gallery/Gallery-Euler2.jpg" />
+<img width="180px" src="http://www.dealii.org/images/wiki/gallery/euler3.jpg" />
+
+
+## Fun pictures
+
+<img width="200px" src="http://www.dealii.org/images/wiki/gallery/Gallery-golf_ball.png" />
+
+Originally, I only wanted to test a discretization of a sphere, so I created one, attached a boundary object, put it into a Laplace solver where the boundary values are given by |r|, and solved. Out came this picture, which was not quite what I had expected. What had happened is that I created the sphere with a radius 0.8, but the boundary object assumed a radius 1, so all points that were introduced by refining faces on the surface went to a different radius - only the original ones remained at the smaller radius and can now be seen as dimples. That makes for a botched simulation, but a nice picture anyway. (Origin: Wolfgang Bangerth, 2000)
+
+<img width="200px" src="http://www.dealii.org/images/wiki/gallery/earth_mantle.png" />
+
+This is slightly more what I had mind for the sphere (or here, a spherical shell, thresholded by one of the variables in my simulation), some 11 years later. This is essentially output from step-32. (Origin: Wolfgang Bangerth, 2011)
+
+<img width="200px" src="http://www.dealii.org/images/wiki/gallery/Gallery-buckling-cylinder-3.png" />
+
+Not an accident, but not very realistic either: this is from a program that computes large deformations of objects. At the time when this picture was made, it could only handle some sort of elastic deformation, although it is nonlinear since the mesh is moved in each time step according to the incremental displacement computed. However, it has no notion of parts of the body coming into contact with each other, and the mesh is also way too coarse to resemble anything useful. Nevertheless, it shows something that looks physical, namely a pipe under vertical compression, where the bottom surface is completely clamped whereas the top surface can move horizontally, but is subjected to a prescribed vertical compression. The result is buckling. Pictures of more realistic
+buckling are shown further up on this page. (Origin: Wolfgang Bangerth, 2004)
+
+<img width="200px" src="http://www.dealii.org/images/wiki/gallery/Cube.png" />
+
+Similar direction, different problem: With a second generation of the program that had already computed above cylinder (this time
+using a displacement-based formulation like in the step-18 example program, but also using pressure stabilization), I wanted to
+compute the deformation of a cube under extension. However, the tolerance of the linear solver was not tight enough, rendering
+the solution useless. The reason why the picture has the mottled look is that we deform the mesh based on the computed (wrong) solution, which makes some of the interior cells protrude through the surface we are looking on. In that case, GMV apparently doesn't quite know any more which cells to plot (the cells do intersect and overlap, after all), and decides on a somewhat random, if appealing, pattern. The quantity shown is the norm of the average stress inside each cell. (Origin: Wolfgang Bangerth, 2005)
+
+<img width="150px" src="http://www.dealii.org/images/wiki/gallery/Gallery-rotation.jpg" />
+
+When changing the numbering to something regular, some of the structures in DataOutRotation were forgotten. Instead of iso-surfaces symmetric to the center, we got this nice picture looking a bit like a complicated turbine. Guido Kanschat 08:10, 17 January 2006 (CET)
+
+<img width="400px" src="http://www.dealii.org/images/wiki/gallery/Gallery-PacmanBenchmark.png" />
+
+Poisson equation with homogeneous Dirichlet boundary conditions solved using Rvachev R-functions method combined with finite elements. Mesh is nonconforming, boundary conditions are enforced exactly. Pacman domain is considered as a benchmark because it contains curved parts as well as reentrant corner :)
+
+For those who are interested to learn a bit about theory of R-functions, [here is a link](http://onlinelibrary.wiley.com/doi/10.1002/pamm.200701055/abstract) to my old 2-pages conference paper. More detailed  and extensive info in English is available at [Spatial Automation Lab](http://sal-cnc.me.wisc.edu/).
+
+-Slawa, 07:21, 6 September 2010 (UTC)
+
+
+<img width="200px" src="http://www.dealii.org/images/wiki/gallery/Gallery-Solidification-Tree.png" />
+
+This had to be a simulation of directional solidification/dendritic growth. But something was wrong with the model and it produced such a nice tree in the end :)
+
+-Slawa, 08:08, 6 September 2010 (UTC)
\ No newline at end of file
diff --git a/Interfacing-With-Matlab.md b/Interfacing-With-Matlab.md
new file mode 100644 (file)
index 0000000..00c1364
--- /dev/null
@@ -0,0 +1,90 @@
+# A few hints about interfacing with Matlab
+
+## Introduction
+
+While deal.II offers a lot of possibilities to output data in different formats to produce awesome graphics, sometimes you experience the need to evaluate the data directly. Most of the deal.II classes have methods to temporarily write out raw data (e.g. Vector::block_write, etc.), and maybe you find it useful to load and modify the data in an environment like Matlab. The following scripts enable reading and writing of deal.II vector data, codes to process matrices may follow.
+
+These codes should be easy to port to Octave.
+
+<wiki:toc  />
+
+## Reading vectors
+
+```
+function v = read_deal_vec(file, accuracy);
+% function vect = read_deal_vec(file);
+% function vect = read_deal_vec(file, accuracy);
+%
+% reads in a DEAL.II vector, written by Vector<>::block_write().
+% The vector is stored in "file", which can be either a filename or
+% a file handle. If you supply a filename, the file will be closed
+% automatically.
+% You usually only supply a file handle if more than one vector is
+% stored within the file.
+% "Accuracy" can be given if you stored a vector storing floats or
+% long doubles. It is by default set to 'double'.
+%
+% Ralf B. Schulz, 2003--2005
+
+if(nargin < 2),  accuracy = 'double'; end;
+
+if(isnumeric(file))
+    closefile = 0;
+else
+    file = fopen(file, 'r');
+    closefile = 1;
+end;
+
+n = fscanf(file,'%d',1)
+v = zeros(1,n);
+while(fscanf(file,'%c',1) ~= '[end;
+
+v = fread(file, n, accuracy);
+
+if(fscanf(file,'%c',1) ~= ']('),)'), error('wrong file format!'); end;
+
+if(closefile)
+    fclose(file);
+end;
+```
+
+## Writing Vectors
+
+```
+function write_deal_vec(file, vec, accuracy);
+% function write_deal_vec(file, vector);
+% function write_deal_vec(file, vector, accuracy);
+%
+% writes out a DEAL.II vector that can be read in using
+% Vector<>::block_read(). The vector is stored in "file", 
+% which can be either a filename or a file handle. If you 
+% supply a filename, the file will be closed automatically.
+% You usually supply a file handle if more than one vector is
+% to be written to the file.
+% "Accuracy" can be given if you stored a vector storing floats or
+% long doubles. It is by default set to 'double'.
+%
+% Ralf B. Schulz, 2003--2005
+
+if(nargin<3)
+    accuracy = 'double';
+end;
+
+vec = vec(:);
+
+if(isnumeric(filename))
+   file = filename;
+   closefile = 0;
+else
+    file = fopen(filename, 'w');
+    closefile = 1;
+end;
+
+fprintf(file,'%d\n[length(vec));
+fwrite(file, vec, accuracy);
+fprintf(file,'](',)\n');
+
+if(closefile)
+    fclose(file);
+end;
+```
diff --git a/Literature.md b/Literature.md
new file mode 100644 (file)
index 0000000..a0589d5
--- /dev/null
@@ -0,0 +1,23 @@
+# Some books on the finite element method
+
+## Literature on learning finite elements
+
+### English
+
+ - <b>Dietrich Braess</b>: Finite Elements : Theory, Fast Solvers, and Applications in Solid Mechanics, Cambridge
+   - Exposition of the method and theoretical results with some not so standard applications
+
+ - <b>Susanne C. Brenner, L. Ridgway Scott</b>: The Mathematical Theory of Finite Element Methods, Springer, 2002
+   - Excellent introduction into the theory of finite elements, including multigrid and Schwarz solvers. Recommended for mathematicians.
+
+ - <b>Philippe G. Ciarlet</b>: The Finite Element Method for Elliptic Problems, SIAM Classics in Applied Mathematics
+    - Very abstract, but still the bible.
+
+
+### German
+
+ - <b>Christian Großmann, Hans-Görg Roos</b>: Numerik partieller Differentialgleichungen, Teubner
+   - Probably the best exposition for students and researchers available.
+ - <b>Hans Rudolf Schwarz</b>: Methode der finiten Elemente, Teubner
+   - Although some of the coding considerations are hopelessly outdated, the book is a good introduction to finite elements from a practical point of view.
\ No newline at end of file
diff --git a/MacOSX.md b/MacOSX.md
new file mode 100644 (file)
index 0000000..0181f15
--- /dev/null
+++ b/MacOSX.md
@@ -0,0 +1,563 @@
+# Using deal.II on Mac OS X
+
+<!-- No auto-Table of Contents support! -->
+
+# Installing the prepacked image file
+
+The easiest way to install dealII on Mac OS X is downloading the prepacked image fils from the download page. Simply download and install. deal.II is found in the subdirectory Library under the installation target
+
+# Instructions for Mac 10.9 Users, Deal.II ver. 8.0 or later (current trunk)
+
+From Mac OS 10.9 onwards, Apple changed quite a few things in their developer tools. You should install XCode 5 **and** its command line tools. If you only do this, however, the installer  will not populate /usr/lib and /usr/include as it used to do, since from Mac OS 10.9, they decided that everything should be self contained in specific SDK directories. If you want to have the standard locations populated (to have, among others, zlib.h, etc.) you should also run the following command:
+  
+```
+xcode-select --install
+```
+
+which will download and install a lot of useful things for us.
+
+If you decide to compile everything yourself, you should follow the instructions below. Otherwise we provide a useful package containing all precompiled libraries for the full optional deal.II under the Downloads section of this site.
+
+# Simple instructions for Mac 10.8 Users, Deal.II ver. 8.1
+
+Here are instructions for a minimal deal.II installation (without other packages):
+  1. Install XCode
+  1. Install XCode "command line tools" (you can find them under preferences->Downloads->Components).
+  1. Install cmake (download Mac OSX 64/32-bit Universal .dmg file, click to install, hit "install links into /local/bin")
+  1. Test that cmake works by running "cmake --version" in a terminal
+  1. Now proceed as explained in the deal.II readme (download the .tar.gz, extract using "tar xf deal.II-8.1.0.tar.gz", create build directory, cd into it)
+  1. You may need to overwrite the cxx compiler by calling:
+      cmake -D CMAKE_CXX_COMPILER=clang++ ..
+  1. Now proceed with "make install" and "make test"
+
+
+# Instructions for Mac 10.8 Users, Deal.II ver. 8.0 or later (current trunk)
+
+Recent Mac Versions come with Apple own version of gcc and clang compilers. They are both based on LLVM backend, but they behave slightly differently. 
+
+**If you want to use deal.II in conjunction with Trilinos, then you should install the macports compiler gcc47**.
+
+Step by step instructions (Working on Mac OS 10.8.8 and XCode 4.6.2): 
+
+  1. Install XCode
+  1. Install XCode "command line Tools" (you can find them under preferences->Downloads->Components).
+  1. (**only if you want to use also Trilinos**) Install macports (http://www.macports.org/)
+  1. Install gcc47
+```
+sudo port install gcc47
+```
+  1. **Optional**: install all additional packages you might want to use with `deal.II`. For example:
+```
+sudo port install arpack +gcc47 
+sudo port install tbb +gcc47
+sudo port install netcdf +gcc47
+sudo port install boost +gcc47
+sudo port install suitesparse +gcc47
+sudo port install metis +gcc47
+sudo port install qt4-mac +gcc47
+```
+
+The openmpi package that comes with macports will not work properly with Trilinos. You should install it from scratch if you want mpi support.
+
+I have customised my profile file in order to allow me to switch from one compiler to another in a relatively easy way, maintaining a reasonable structure in the libraries that I install, without the need to recompile everything when I change my mind. I try to use the same compiler for all the libraries I use, and to keep copies around of the compiled libraries in order to have a "backup plan" when things go wrong with my own deal.II experiments...
+
+I usually keep all source files under the same directory (`$SRC`), build in subdirectories (`$SRC/library-name/$TYPE`) of the source directories, and install in separate "destination" directories (`$DST/library-name-$TYPE`). Of  course this is my personal taste. You can easily change this below....
+
+At the end of your `~/.profile` file, add the following lines:
+```
+# Available compilers: native, gcc, openmpi
+. ~/.profile-libs gcc
+```
+
+Create the file `~/.profile-libs`, which will accept a command line argument specifying the compiler to use:
+```
+# TYPE is the first argument 
+TYPE=$1
+
+# Versions of the external libraries we want to compile/install
+TRILINOS_VER=11.0.3
+P4EST_VER=0.3.4
+
+# Where source directories and install destination should be.
+SRC=~/libs_src
+DST=~/libs
+
+# Change the following to suite your own system
+case "$TYPE" in
+native)
+    export CC=/usr/bin/clang
+    export CXX=/usr/bin/clang++
+    export USE_MPI=OFF
+    ;;
+gcc)
+    export CC=/opt/local/bin/gcc-mp-4.7 
+    export CXX=/opt/local/bin/g++-mp-4.7 
+    export USE_MPI=OFF
+    ;;
+openmpi)
+    export CC=/usr/local/bin/mpicc
+    export CXX=/usr/local/bin/mpic++
+    export USE_MPI=ON
+    ;;
+esac
+
+export DEAL_II_SRC=$SRC/deal.II
+export P4EST_SRC=$SRC/p4est-$P4EST_VER
+export TRILINOS_SRC=$SRC/trilinos-$TRILINOS_VER-Source
+
+export DEAL_II_BUILD=$DEAL_II_SRC/$TYPE
+export TRILINOS_BUILD=$TRILINOS_SRC/$TYPE
+export P4EST_BUILD=$P4EST_SRC/$TYPE
+
+export DEAL_II_DIR=$DST/deal.II-$TYPE
+export P4EST_DIR=$DST/p4est-$P4EST_VER-$TYPE
+export TRILINOS_DIR=$DST/trilinos-$TRILINOS_VER-$TYPE
+
+export DYLD_LIBRARY_PATH=$TRILINOS_DIR/lib
+
+```
+
+This assumes you have downloaded all your packages under `$SRC`, and that you are installing them under `$DST`. Change these to your liking. 
+
+## Trilinos 11.0.3
+
+Once the above environment variables are set, you can install Trilinos using the following script:
+
+### trilinos.sh
+
+```
+EXTRA_ARGS=$@
+
+if [ ! -d "$TRILINOS_BUILD" ]; then
+       mkdir $TRILINOS_BUILD
+fi
+cd  $TRILINOS_BUILD
+
+cmake \
+-D TrilinosFramework_ENABLE_MPI:BOOL=$USE_MPI \
+-D CMAKE_INSTALL_PREFIX:PATH=$TRILINOS_DIR \
+-D TPL_ENABLE_MPI:BOOL=$USE_MPI \
+-D BUILD_SHARED_LIBS:BOOL=ON \
+-D CMAKE_BUILD_TYPE:STRING=RELEASE \
+-D Trilinos_ENABLE_Fortran:BOOL=OFF \
+-D Trilinos_WARNINGS_AS_ERRORS_FLAGS:STRING="" \
+-D CMAKE_VERBOSE_MAKEFILE:BOOL=TRUE \
+-D Trilinos_ENABLE_TESTS:BOOL=OFF \
+-D Trilinos_ENABLE_ALL_PACKAGES:BOOL=OFF \
+-D Trilinos_ENABLE_ALL_OPTIONAL_PACKAGES:BOOL=ON \
+-D Trilinos_ENABLE_Epetra:BOOL=ON \
+-D Trilinos_ENABLE_EpetraExt:BOOL=ON \
+-D Trilinos_ENABLE_Tpetra:BOOL=ON \
+-D Trilinos_ENABLE_Jpetra:BOOL=ON \
+-D Trilinos_ENABLE_Kokkos:BOOL=ON \
+-D Trilinos_ENABLE_Sacado:BOOL=ON \
+-D Trilinos_ENABLE_Amesos:BOOL=ON \
+-D Trilinos_ENABLE_AztecOO:BOOL=ON \
+-D Trilinos_ENABLE_Ifpack:BOOL=ON \
+-D Trilinos_ENABLE_Teuchos:BOOL=ON \
+-D Trilinos_ENABLE_Rythmos:BOOL=ON \
+-D Trilinos_ENABLE_Piro:BOOL=ON \
+-D Trilinos_ENABLE_MOOCHO:BOOL=ON \
+-D Trilinos_ENABLE_ML:BOOL=ON \
+-D Trilinos_ENABLE_Thyra:BOOL=ON \
+-D Trilinos_ENABLE_TrilinosCouplings:BOOL=ON \
+$EXTRA_ARGS \
+../
+
+make -j2 install
+```
+
+## p4est
+
+The following script will install p4est. It has been modified from the file `doc/p4est-setup.sh` in the p4est distribution, to use the variables which where set in the environment.
+
+### p4est.sh
+
+```
+#! /bin/bash
+
+# This program comes with ABSOLUTELY NO WARRANTY.
+
+UNPACK=$P4EST_SRC
+
+# choose names for fast and debug compilation directories
+BUILD_DIR="$P4EST_BUILD"
+BUILD_FAST="$BUILD_DIR/FAST"
+BUILD_DEBUG="$BUILD_DIR/DEBUG"
+
+function busage() {
+        echo "Usage: `basename $0` <p4est_tar.gz_file> [location>](<install)"
+}
+function bdie () {
+        echo "Error: $@"
+        exit 1
+}
+
+
+if test -z "$CFLAGS" -a -z "$P4EST_CFLAGS_FAST" ; then
+        export CFLAGS_FAST="-O2"
+else
+        export CFLAGS_FAST="$CFLAGS $P4EST_CFLAGS_FAST"
+fi
+echo "CFLAGS_FAST: $CFLAGS_FAST"
+if test -z "$CFLAGS" -a -z "$P4EST_CFLAGS_DEBUG" ; then
+        export CFLAGS_DEBUG="-O0 -g"
+else
+        export CFLAGS_DEBUG="$CFLAGS $P4EST_CFLAGS_DEBUG"
+fi
+echo "CFLAGS_DEBUG: $CFLAGS_DEBUG"
+
+# choose names for fast and debug installation directories
+INSTALL_DIR="$P4EST_DIR"
+INSTALL_FAST="$INSTALL_DIR/FAST"
+INSTALL_DEBUG="$INSTALL_DIR/DEBUG"
+
+echo
+echo "This script tries to unpack, configure and build the p4est library."
+echo "Build FAST: $BUILD_FAST"
+echo "Build DEBUG: $BUILD_DEBUG"
+echo "Install FAST: $INSTALL_FAST"
+echo "Install DEBUG: $INSTALL_DEBUG"
+echo "Checking environment: CFLAGS P4EST_CFLAGS_FAST P4EST_CFLAGS_DEBUG"
+
+# remove old versions
+if test -d "$BUILD_DIR" ; then
+        rm -rf "$BUILD_DIR"
+fi
+
+test -f "$UNPACK/src/p4est.h" || bdie "Main header file missing"
+test -f "$UNPACK/configure" || bdie "Configure script missing"
+
+echo "See output in files .../config.output and .../make.output"
+echo
+echo "Build FAST version in $BUILD_FAST"
+mkdir -p "$BUILD_FAST"
+cd "$BUILD_FAST"
+
+if [ "$USE_MPI" == "ON" ]; then
+    ENABLE_MPI=--enable-mpi
+else
+    ENABLE_MPI=""
+fi
+
+"$UNPACK/configure" $ENABLE_MPI --enable-shared \
+        --disable-vtk-binary --with-blas \
+        --prefix="$INSTALL_FAST" CFLAGS="$CFLAGS_FAST" \
+        CPPFLAGS="-DSC_LOG_PRIORITY=SC_LP_ESSENTIAL" \
+        "$@" > config.output || bdie "Error in configure"
+make -C sc -j 8 > make.output || bdie "Error in make sc"
+make -j 8 >> make.output || bdie "Error in make p4est"
+make install >> make.output || bdie "Error in make install"
+echo "FAST version installed in $INSTALL_FAST"
+
+echo
+echo "Build DEBUG version in $BUILD_DEBUG"
+mkdir -p "$BUILD_DEBUG"
+cd "$BUILD_DEBUG"
+"$UNPACK/configure" --enable-debug $ENABLE_MPI --enable-shared \
+        --disable-vtk-binary --without-blas \
+        --prefix="$INSTALL_DEBUG" CFLAGS="$CFLAGS_DEBUG" \
+        CPPFLAGS="-DSC_LOG_PRIORITY=SC_LP_ESSENTIAL" \
+        "$@" > config.output || bdie "Error in configure"
+make -C sc -j 8 > make.output || bdie "Error in make sc"
+make -j 8 >> make.output || bdie "Error in make p4est"
+make install >> make.output || bdie "Error in make install"
+echo "DEBUG version installed in $INSTALL_DEBUG"
+echo
+
+```
+
+## Deal.II
+
+And finally, the deal.II library. Please consider using this script, since it will automatically 
+feed the *build tests* page with the outcome of your compilation.
+
+### deal.sh
+
+```
+if [ ! -d "$DEAL_II_BUILD" ]; then
+       mkdir $DEAL_II_BUILD
+fi
+
+NAME=`basename $DEAL_II_BUILD`
+cp deal.conf $DEAL_II_BUILD/$NAME
+
+cd $DEAL_II_SRC
+svn update
+
+LOGFILE=/usr/local/src/conf-scripts/deal.log
+
+umask 0006
+
+$DEAL_II_SRC/contrib/utilities/build_test -j4 \
+       CONFIGFILE=$DEAL_II_BUILD/$NAME \
+       SOURCE_DIR=$DEAL_II_SRC \
+       builddir=$DEAL_II_BUILD \
+       installdir=$DEAL_II_DIR \
+       LOGFILE=$LOGFILE \
+       MAKEOPTS=-j2 \
+       CLEAN_TMPDIR=false
+
+grep SUCCESSFUL $LOGFILE && mail  dealii.build.tests@gmail.com < $LOGFILE 
+
+```
+
+## Using deal.II with Xcode IDE
+
+Setting up Xcode for use of the deal.II libraries requires lots of project specifications that can automatically be generated by CMake. The following procedure covers the installation of necessary tools, the compilation of the deal.II libraries and the Xcode project generation. It was tested with Mac OS X 10.8.4, Xcode 4.6.3, CMake 2.8.10.2 and deal.II 8.0pre.
+
+First, install Xcode (via the app store) and MacPorts (available on http://www.macports.org). Then install CMake with the terminal command
+```
+sudo port install cmake
+```
+Create a new folder on your machine somewhere and change to it in terminal. Then download the current deal.II version by typing
+```
+svn checkout https://svn.dealii.org/trunk/deal.II
+```
+Change to the deal.II subdirectory
+```
+cd deal.II
+```
+Create new build directory and change to it
+```
+mkdir build
+cd build
+```
+Run cmake to prepare compilation
+```
+cmake -DCMAKE_INSTALL_PREFIX=/Users/Username/libs/deal_8.0.pre ..
+```
+where the path is the directory where the deal.II library will be installed, change it as you like.
+Compile the library
+```
+make -j8
+make install
+```
+8 is the number of cores your machine has, change this if necessary. The first command might take a while (up to one hour). After compilation, the whole deal.II directory can be deleted, as the library is now installed in the path specified above (INSTALL_PREFIX). Go to the specified directory and change to the step-1 example folder. Run cmake to prepare example to be used with Xcode
+```
+cmake -G Xcode -DDEAL_II_DIR=/Users/Username/libs/deal_8.0.pre .
+```
+The DDEAL_II_DIR is the directory where the library is to be found, like specified before (INSTALL_PREFIX). The file step-1.xcodeproj is now generated and can be opened with Xcode. A click on RUN should compile the code into subdirectory "Debug", but not execute it. For build and run change Product -> Scheme to 'step-1'. Code completion, compiling and debugging should be working now. If you add a new class, activate target membership step-1 so that the class is automatically compiled when clicking on run.
+
+
+## Getting rid of pop-ups when running executables compiled with deal.II
+
+When running an deal.II executable that uses MPI on a mac with the firewall or parental control enabled, a pop-up appears that asks 
+"Do you want the application xxx to accept incoming network connections?". It pops up as many MPI precesses you asked for which becomes
+annoying. The way to prevent the pop-up is to code sign your executable. If you have a code signing certificate, configure you project 
+using the OSX_CERTIFICATE_NAME feature:
+```
+cmake -DOSX_CERTIFICATE_NAME="put your code signing certificate name here" .
+```
+The executable will be signed using the certificate every time it is recompiled.
+
+If you don't have a certificate or you are not sure, then follow these instructions:
+
+  1. Open Keychain Access.
+  1. Choose Keychain Access->Certificate Assistant->Create a certificate.
+  1. Choose a name for the certificate (Something like "deal.II developer").
+  1. Choose Certificate Type "Code Signing".
+  1. Check "Let me override defaults".
+  1. Press Continue.
+  1. Write any serial number you want (the name and serial number must be unique in the system).
+  1. Select how many days you want the certificate to be valid (2000 is just above 5 years).
+  1. Press Continue then put your personal data (nobody will see that but you so you can have fun with it).
+  1. Press Continue to get Key Pair Information. Keep as is.
+  1. Press Continue to get Key Usage Extension. Keep as is.
+  1. Press Continue to get Extended Key Usage Extension. Keep as is.
+  1. Press Continue to get Basic Constraints Extension. Keep as is.
+  1. Press Continue to get Subject Alternate Name Extension. Keep as is.
+  1. Press Continue and keep the Keychain "login" selected.
+  1. Press Continue then Done.
+  1. Right Click on your newly generated certificate.
+  1. Select "Get Info"
+  1. Select the triangle next to "Trust"
+  1. Scroll down to "Code Signing" and change it "Always Trust"
+  1. The system will ask for the administrator password to allow the changes. Enter it and press OK.
+
+Now you have a code signing certificate that you can use with deal.II. Configure the project with the new certificate with a command line like this:
+```
+cmake -DOSX_CERTIFICATE_NAME="deal.II developer" .
+```
+
+
+
+---- 
+# Older instructions
+
+---- 
+
+## Installation without PETSc and Trilinos
+
+The installation of deal.II without support for Petsc and Trilinos is standard.
+The gcc that comes with the latest version of Xcode works without problems.
+At the time of writing this was gcc version 4.2.1 (Apple Inc. build 5646) (dot 1).
+It is suggested that you use the latest version of Xcode available from
+[## Dynamic libraries not found
+
+If you get a message of the kind
+
+```
+dyld: Library not loaded: libdeal_II_2d.g.6.2.1.dylib
+  Referenced from: /Users/.../deal.II/examples/step-1/./step-1
+  Reason: image not found
+make: *** [run](http://developer.apple.com/technologies/tools/xcode.html]) Trace/BPT trap
+```
+
+you have to set the path for dynamical libraries. Using <tt>csh</tt> or <tt>tcsh</tt>, this reads
+```
+setenv DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:/Users/.../deal.II/lib
+```
+
+while <tt>bash</tt> users use
+```
+export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:/Users/.../deal.II/lib
+```
+
+
+
+## Compiling Trilinos without Fortran support
+
+One of the major hassles with using deal.II on a mac was compiling Trilinos which required fortran support.
+It now seems possible to compile Trilinos 10.4.1  with all the features needed for deal.ii without fortran support. This is very nice as you can then simply use the mac gcc compilers and not worry about all the compatibility issues.
+
+Here is my configure script:
+
+```
+EXTRA_ARGS=$@
+TRILINOS_HOME=/Users/andrewmcbride/lib/trilinos-10.4.1-Source
+
+ cmake \
+ -D CMAKE_INSTALL_PREFIX:PATH=/Users/andrewmcbride/lib/trilinos-10.4.1-Source/MAC_SL \
+ -D CMAKE_BUILD_TYPE:STRING=RELEASE \
+ -D BUILD_SHARED_LIBS:BOOL=ON \
+ -D TPL_ENABLE_MPI:BOOL=OFF \
+ -DCMAKE_C_FLAGS:STRING="-fPIC" \
+ -DCMAKE_CXX_FLAGS:STRING="-fPIC" \
+ -D Trilinos_ENABLE_ALL_PACKAGES:BOOL=OFF \
+ -D Trilinos_ENABLE_Stratimikos:BOOL=ON \
+ -D Trilinos_ENABLE_Sacado:BOOL=ON \
+ -D Trilinos_ENABLE_NOX-Epetra:BOOL=OFF \
+ -D Trilinos_ENABLE_ALL_OPTIONAL_PACKAGES:BOOL=ON \
+ -D Trilinos_ENABLE_Fortran:BOOL=OFF \
+ -D CMAKE_CXX_COMPILER:FILEPATH=/usr/bin/g++ \
+ -D CMAKE_C_COMPILER:FILEPATH=/usr/bin/gcc \
+ $EXTRA_ARGS \
+ ${TRILINOS_HOME}
+```
+
+## Fortran support
+
+Xcode does not provide support for Fortran.
+This is needed (at present but see comments above) to compile Trilinos and PETSc with reasonable features.
+To get the Fortan compilers on your mac you can follow one of several routes.
+
+ 1. Install the precompiled high performance gcc libraries with Fortan support avaialble from  [A known problem with the latest release of these gcc libraries is said to be fixed (see [http://gcc.gnu.org/bugzilla/show_bug.cgi?id=43648](http://sourceforge.net/projects/hpc/]))
+
+ 1. Build gcc with fortran support from source available from [http://gcc.gnu.org/]
+
+ 1. Install gcc with fortran support using macports or similar.
+This has never worked for me.
+
+You will then need to install deal.II using these libraries: for example on my
+mac the configure looks like this (no trilinos or petsc)
+```
+  $ ./configure --with-umfpack --with-blas --with-lapack
+  CC=/Users/andrewmcbride/lib/gcc_snwleo/usr/local/bin/gcc
+  CXX=/Users/andrewmcbride/lib/gcc_snwleo/usr/local/bin/g++
+  F77=/Users/andrewmcbride/lib/gcc_snwleo/usr/local/bin/gfortran
+  --with-doxygen=/Applications/Doxygen.app/Contents/Resources/doxygen
+```
+
+## Dynamic_cast bug
+
+Due to inconsistencies between the Xcode and standard gcc releases a bug arose that caused deal.II to "crash" when performing certain dynamic casts.
+A work around this problem was implemented in December 2009.
+It is suggested that you install the svn version of deal.II to ensure this problem does not arise
+
+
+## Installation with Trilinos 10.2 and CMake
+
+The latest versions of Trilinos require one to use the CMake build system, which requires some system configuration up front.  These steps were followed to obtain a working installation of Trilinos with MPI and deal.II.
+
+On a fully updated 10.6 (Snow Leopard) machine, you should be able to install mac ports, and then install their versions of gcc45 and cmake.  To get a Fortran MPI compiler, you can download the latest version of OpenMPI, and compile it with the MacPorts gcc45, and install it in some directory (NOT the system one!!), making sure that the new /bin directory is in your PATH first.
+
+Next, download and untar the Trilinos source, then create a directory where you want to build Trilinos.  Inside of that directory, copy the following into a text file:
+
+```
+ #!/bin/sh
+
+ EXTRA_ARGS=$@
+
+ rm -f CMakeCache.txt
+
+ cmake \
+ -D TrilinosFramework_ENABLE_MPI:BOOL=ON \
+ -D CMAKE_INSTALL_PREFIX=/path_to/trilinos_install_dir \
+ -D TPL_ENABLE_MPI:BOOL=ON \
+ -D MPI_BASE_DIR:PATH=/path_to_custom_MPI_install/mpi \
+ -D BUILD_SHARED_LIBS:BOOL=ON \
+ -D CMAKE_BUILD_TYPE:STRING=DEBUG \
+ -D CMAKE_CXX_COMPILER:FILEPATH=mpicxx \
+ -D CMAKE_C_COMPILER:FILEPATH=mpicc \
+ -D CMAKE_Fortran_COMPILER:FILEPATH=mpif90 \
+ -D Trilinos_WARNINGS_AS_ERRORS_FLAGS:STRING="" \
+ -D CMAKE_VERBOSE_MAKEFILE:BOOL=TRUE \
+ -D Trilinos_ENABLE_TESTS:BOOL=OFF \
+ -D Trilinos_ENABLE_ALL_PACKAGES:BOOL=TRUE \
+ -D Trilinos_ENABLE_ALL_OPTIONAL_PACKAGES:BOOL=ON \
+ -D Trilinos_ENABLE_Epetra:BOOL=ON \
+ -D Trilinos_ENABLE_EpetraExt:BOOL=ON \
+ -D Trilinos_ENABLE_Tpetra:BOOL=ON \
+ -D Trilinos_ENABLE_Jpetra:BOOL=ON \
+ -D Trilinos_ENABLE_Kokkos:BOOL=ON \
+ -D Trilinos_ENABLE_Sacado:BOOL=ON \
+ -D Trilinos_ENABLE_Amesos:BOOL=ON \
+ -D Trilinos_ENABLE_AztecOO:BOOL=ON \
+ -D Trilinos_ENABLE_Ifpack:BOOL=ON \
+ -D Trilinos_ENABLE_Teuchos:BOOL=ON \
+ -D Trilinos_ENABLE_ML:BOOL=ON \
+ -D Trilinos_ENABLE_Thyra:BOOL=ON \
+ -D Trilinos_ENABLE_TrilinosCouplings:BOOL=ON \
+ $EXTRA_ARGS \
+ /path_to/trilinos-10.2.2-Source
+```
+
+Note that you will have to specify the paths for where to install Trilinos, where to find the source, and where to find your newly compiled MPI.  Next, you should give this text file executable permissions, and run it; Trilinos will configure.  You should then be able to compile it using 'make all -jX', where X is the number of cores you have, and then 'make install'.
+
+To configure deal.II, you should set the environment variable 'TRILINOS_DIR' to your install directory for Trilinos, then export the /lib subdirectory of that location to the DYLD_LIBRARY_PATH.  You should then be able to configure deal.II and have it see the installation.
+
+Note: additional packages can be added by simply adding another line like {{{-D Trilinos_ENABLE_AztecOO:BOOL=ON}}}  Also, there is no claim that this list of options is complete/optimal, but it seems to work well for the author of this note.
+
+
+
+## Teuchos Error (Trilinos 10.4.1) when deal.II is Configured with Mumps, Blacs, Petsc and Trilinos 10.4.1
+
+When deal.ii was configured to use Mumps and Blacs like so:
+
+```
+        ./configure --enable-shared --disable-threads \
+                    --with-cpu=native --with-umfpack  \
+                    --with-mumps=PATH-TO-MUMPS \
+                    --with-scalapack=PATH-TO-SCALAPACK \
+                    --with-blacs=PATH-TO-BLACS  --with-lapack=lapack \
+                    --with-metis-libs=/opt/local/lib \
+                    --with-trilinos=PATH-TO-TRILINOS
+```
+
+the following error occurred during compilation:
+
+```
+        ============================ Compiling expand_instantiations
+        ============================ Compiling report_features
+        Undefined symbols:
+        "Teuchos::PrintActiveRCPNodes::PrintActiveRCPNodes()", referenced from:
+         global constructors keyed to report_features.cc in ccnoQB3F.o
+        "Teuchos::PrintActiveRCPNodes::~PrintActiveRCPNodes()", referenced from:
+        global constructors keyed to report_features.cc in ccnoQB3F.o
+        ld: symbol(s) not found
+```
+
+Removing {{{--with-mumps and --with-blacs}}} allowed successful compilation.
+
+The compilers used above were OpenMPI's MPI wrappers (including the Fortran MPI compiler), which were compiled with Macports' gcc45.
\ No newline at end of file
diff --git a/Mesh-Input-And-Output.md b/Mesh-Input-And-Output.md
new file mode 100644 (file)
index 0000000..eb85583
--- /dev/null
@@ -0,0 +1,212 @@
+# A little script to illustrate exchanging data with Cubit
+
+### Cubit
+
+The following cubit journal file (Actually a pyton script) exports the current mesh and 
+boundary conditions from cubit to a file "output.ucd" in the current directory.
+
+This is a modification of the original script that takes into account boundary ids via
+sidesets ids. If you want to save the boundary faces as well, you just need to 
+add the relevant surfaces in 3d or curves in 2d to a sideset, and the id will be the one of the
+sideset. 
+
+```
+#!python
+# This script will output whatever mesh you have currently in CUBIT
+# in the AVS UCD format. (http://www.csit.fsu.edu/~burkardt/data/ucd/ucd.html)
+# You may need to tweak it to get exactly what you want out of
+# it.  Your mileage may vary.
+
+# set the filename -- you may need the entire path
+outucdfile = "output.inp"
+
+outfile = open(outucdfile,"w")
+
+cubit.cmd("body all rotate -90 about y")
+cubit.cmd("body all reflect x")
+
+# ============================================================
+# Collect all the nodes
+# ============================================================
+group_id = cubit.get_id_from_name("temp_bc_curves")
+if group_id != 0:
+  cubit.cmd("delete group " + str(group_id))
+cubit.cmd("group 'temp_nodes' add node all")
+group_id = cubit.get_id_from_name("temp_nodes")
+node_list = cubit.get_group_nodes(group_id)
+cubit.cmd("delete group " + str(group_id))
+n_nodes = len(node_list)
+
+# ============================================================
+# Collect all the hex
+# ============================================================
+group_id = cubit.get_id_from_name("temp_hexes")
+if group_id != 0:
+  cubit.cmd("delete group " + str(group_id))
+cubit.cmd("group 'temp_hexes' add hex all")
+group_id = cubit.get_id_from_name("temp_hexes")
+hex_list = cubit.get_group_hexes(group_id)
+cubit.cmd("delete group " + str(group_id))
+n_hex_cells = len(hex_list)
+
+
+# ============================================================ 
+# Now the boundary conditions in 3d
+# ============================================================
+bc_surfaces = {}
+n_bc_quads = 0
+
+bc_ids = cubit.get_sideset_id_list()
+for bc_id in bc_ids :
+  bc_surfaces[= cubit.get_sideset_surfaces(bc_id)
+  for bc_surface in  bc_surfaces[bc_id](bc_id]):
+    bc_quads = cubit.get_surface_quads(bc_surface)
+    n_bc_quads += len(bc_quads)
+
+
+# ============================================================ 
+# Collect all the surfaces. Notice that the surfaces that make up a
+# volume are not grouped here. This is only for 2d objects, i.e.,
+# when the number n_hex_cells is zero.
+# ============================================================
+surface_list = ()
+quad_cell_list = {}
+n_quad_cells = 0
+if n_hex_cells == 0:
+  group_id = cubit.get_id_from_name("temp_surfs")
+  if group_id != 0:
+    cubit.cmd("delete group " + str(group_id))
+  cubit.cmd("group 'temp_surfs' add surf all")
+  group_id = cubit.get_id_from_name("temp_surfs")
+  surface_list = cubit.get_group_surfaces(group_id)
+  cubit.cmd("delete group " + str(group_id))
+  for surface_id in surface_list:
+    quad_cell_list[= cubit.get_surface_quads(surface_id)
+    n_quad_cells +=  len(quad_cell_list[surface_id](surface_id]))
+
+# ============================================================ 
+# Now the boundary conditions in 2d
+# ============================================================
+bc_curves = {}
+bc_edges = {}
+n_bc_edges = 0
+if n_hex_cells == 0:
+  bc_ids = cubit.get_sideset_id_list()
+  for bc_id in bc_ids :
+    bc_curves[= cubit.get_sideset_curves(bc_id)
+    group_id = cubit.get_id_from_name("temp_bc_curves")
+    if group_id != 0:
+      cubit.cmd("delete group " + str(group_id))
+    for bc_curve in bc_curves[bc_id](bc_id]):
+      cubit.cmd("group 'temp_bc_curves' add edge all in curve " + str(bc_curve))
+    group_id = cubit.get_id_from_name("temp_bc_curves")
+    bc_edges[= cubit.get_group_edges(group_id)
+    cubit.cmd("delete group " + str(group_id))
+    n_bc_edges +=  len(bc_edges[bc_id](bc_id]))
+
+print 'Edges: ' + str(n_bc_edges)
+
+# ============================================================
+# Now we write the header.
+# ============================================================
+n_elements = n_hex_cells + n_bc_quads + n_quad_cells + n_bc_edges
+outfile.write(str(n_nodes) + " " + str(n_elements) + " 0 0 0\n")
+
+
+# ============================================================
+# The node list.
+# ============================================================
+for node_num in node_list:
+   outfile.write(str(node_num ))
+   outfile.write("\t")
+   node_coord = cubit.get_nodal_coordinates(node_num)
+   if abs(node_coord[outfile.write("0 ")
+   else        :
+       outfile.write(str(node_coord[2](2])<1e-15:)) + " ")
+   if abs(node_coord[outfile.write("0 ")
+   else        :
+       outfile.write(str(node_coord[1](1])<1e-15:)) + " ")
+   if abs(node_coord[outfile.write("0")
+   else        :
+       outfile.write(str(node_coord[0](0])<1e-15:)))
+   outfile.write("\n")
+
+
+# ============================================================
+# The hex list. 3d
+# ============================================================
+k = 1
+for hex_num in hex_list:
+   outfile.write(str(k) + " 0 " + " hex  ")
+   k += 1
+   hex_nodes = cubit.get_connectivity("Hex", hex_num)
+   i = 0
+   while i < 8:
+      outfile.write(str(hex_nodes[+ " ")
+      i += 1
+   outfile.write("\n")
+
+
+# ============================================================
+# The quads on the boundaries. 3d
+# Note that the boundary id is given by the sideset id.
+# ============================================================
+if n_hex_cells != 0:
+  k=1
+  for bc_id in bc_ids:
+    for bc_surface in  bc_surfaces[bc_id](i])):
+      bc_quads = cubit.get_surface_quads(bc_surface)
+      for quad_num in bc_quads:
+        outfile.write(str(k))
+        k += 1
+        outfile.write(" " + str(bc_id) + " quad ")
+        quad_nodes = cubit.get_connectivity("Quad", quad_num)
+        outfile.write(str(quad_nodes[+ " ")
+        outfile.write(str(quad_nodes[3](0]))) + " ")
+        outfile.write(str(quad_nodes[+ " ")
+        outfile.write(str(quad_nodes[1](2]))))
+        outfile.write("\n")
+
+# ============================================================
+# The quads on the surfaces. 2d
+# ============================================================
+if n_hex_cells == 0:
+  k = 1
+  for surface_id in surface_list:
+    for quad_num in quad_cell_list[outfile.write(str(k))
+      k += 1
+      outfile.write(" " + str(surface_id) + " quad ")
+      quad_nodes = cubit.get_connectivity("Quad", quad_num)
+      outfile.write(str(quad_nodes[0](surface_id]:)) + " ")
+      outfile.write(str(quad_nodes[+ " ")
+      outfile.write(str(quad_nodes[2](3]))) + " ")
+      outfile.write(str(quad_nodes[outfile.write("\n")
+
+# ============================================================
+# The edges on the curves. 2d
+# Boundary id = sideset_id
+# ============================================================
+if n_hex_cells == 0:
+  k=1
+  for bc_id in bc_ids:
+    for edge_num in bc_edges[bc_id](1]))):
+      outfile.write(str(k))
+      k += 1
+      outfile.write(" " + str(bc_id) + " line ")
+      edge_nodes = cubit.get_connectivity("Edge", edge_num)
+      outfile.write(str(edge_nodes[+ " ")
+      outfile.write(str(edge_nodes[1](0]))))
+      outfile.write("\n")
+
+outfile.close()
+
+cubit.cmd("body all reflect x")
+cubit.cmd("body all rotate 90 about y")
+
+print str(n_nodes) + " nodes\n"
+print str(n_hex_cells) + " hexes\n"
+print str(n_quad_cells) + " quads\n"
+print str(n_bc_quads) + " face_quads\n"
+print str(n_bc_edges) + " edges\n"
+
+```
diff --git a/Windows.md b/Windows.md
new file mode 100644 (file)
index 0000000..fbcbf85
--- /dev/null
@@ -0,0 +1,39 @@
+# Using deal.II on native Windows
+
+For an overview of different ways to use deal.II on Windows have a look at the corresponding [FAQ entry](https://code.google.com/p/dealii/wiki/FrequentlyAskedQuestions#Can_I_use_deal.II_on_a_Windows_platform?).
+
+
+This page discusses how to compile and run deal.II on native Windows. We currently have experimental support for the gcc compiler ported by the [Cygwin64](http://www.cygwin.com/) and [MinGW-w64](http://mingw-w64.sourceforge.net/) project. Please note, that currently native Windows platforms aren't officially supported, so expect an a "told you so" as answer if something explodes in a funny way ;-)
+
+## Cygwin
+
+deal.II has been developed with a Unix-like environment in mind. Windows does not usually provide something like this, but it can be added to windows through the [Cygwin system](http://www.cygwin.com/). You should always use a current Cygwin distribution.
+
+### What do I need to do to get it running?
+
+ 1. Install the 64bit installer `setup-x86_64.exe` from [1. Install the following additional packages (and its recommended dependencies):
+    - cmake
+    - make
+    - gcc-g++
+    - subversion
+    - libboost-devel
+    - liblapack-devel
+    - libumfpack-devel
+ 1. fire up the Cygwin terminal and proceed with the download and installation process normally. See the [http://www.dealii.org/developer/readme.html readme](http://cygwin.com/]).
+
+## MinGW-w64
+
+If you do not want to use Cygwin but rather a native Windows compiler the [MinGW-w64](http://mingw-w64.sourceforge.net/) project might be of interest for you.
+
+### Compile from source
+
+Due to the fact that this is a highly involved procedure that requires some knowledge, only a rough outline is given:
+
+ 1. Download the online installer from [1. Install a compiler with version 4.8.`*`, target `x86_64` and thread model `TODO`
+ 1. Do not forget to set your path environment variable to the bin folder of your Mingw-w64 installation
+ 1. Download and install [http://cmake.org CMake](http://mingw-w64.sourceforge.net/].).
+ 1. Compile and install deal.II
+
+## Other Windows compilers
+
+If you want to use any of the genuine Windows compilers, such as Visual C++, or Borland C++ this is more difficult. See the entry on this topic in the FrequentlyAskedQuestions.
\ No newline at end of file
diff --git a/dbinit.md b/dbinit.md
new file mode 100644 (file)
index 0000000..3fbb039
--- /dev/null
+++ b/dbinit.md
@@ -0,0 +1,187 @@
+# Code one can put into a .gdbinit file to make gdb work better with deal.II
+
+This is code that makes gdb aware of some of the deal.II classes and able to print their elements in a debugger in a way that is more easily readable.
+See the FrequentlyAskedQuestions for more information.
+
+```
+set print pretty 1
+
+python
+
+import gdb
+import itertools
+import re
+
+# Try to use the new-style pretty-printing if available.
+_use_gdb_pp = True
+try:
+    import gdb.printing
+except ImportError:
+    _use_gdb_pp = False
+
+class PointPrinter:
+    "Print dealii::Point"
+
+    def __init__ (self, typename, val):
+        self.typename = typename
+        self.val = val
+
+    def to_string (self):
+        return '%s' % self.val[class TensorPrinter:
+    "Print dealii::Tensor"
+
+    def __init__ (self, typename, val):
+        self.typename = typename
+        self.val = val
+
+    def to_string (self):
+        1. we could distinguish between Tensor<1,dim> and Tensor<2,dim>
+        1. by asking self.val.type.template_argument(0) but unfortunately
+        1. template_argument does not handle value arguments...
+        try:
+         return self.val['values']('values'])
+       except:
+         return self.val[class TriaIteratorPrinter:
+    "Print dealii::TriaIterator"
+
+    def __init__ (self, typename, val):
+        self.typename = typename
+        self.val = val
+
+    def to_string (self):
+        if re.compile('.*DoF.*').match('%s' % self.val.type.template_argument(0)):
+          return ('{\n  triangulation = %s,\n  dof_handler = %s,\n  level = %d,\n  index = %d\n}' %
+                 (self.val['accessor']('subtensor'])[self.val['accessor']('tria'],)[self.val['accessor']('dof_handler'],)[self.val['accessor']('present_level'],)[else:
+          return ('{\n  triangulation = %s,\n  level = %d,\n  index = %d\n}' %
+                 (self.val['accessor']('present_index'])))[self.val['accessor']('tria'],)[self.val['accessor']('present_level'],)[class VectorPrinter:
+    "Print dealii::Vector"
+
+    class _iterator:
+        def __init__ (self, start, size):
+            self.start = start
+            self.size = size
+            self.count = 0
+
+        def __iter__(self):
+            return self
+
+        def next(self):
+            count = self.count
+            self.count = self.count + 1
+           self.start = self.start + 1
+            if self.count == self.size:
+                raise StopIteration
+            elt = self.start.dereference()
+            return ('[%d]('present_index'])))' % count, elt)
+
+    def __init__ (self, typename, val):
+        self.typename = typename
+        self.val = val
+
+    def children(self):
+        return self._iterator(self.val[self.val['vec_size']('val'],))
+
+    def to_string_x (self):
+        return ('%s[= {%s}' % (self.val.type.template_argument(0),
+                                   self.val['vec_size'](%d]),
+                                  self.val[def to_string (self):
+        return ('%s[%d]('val'].dereference())))' % (self.val.type.template_argument(0),
+                            self.val[def display_hint(self):
+        return 'array'
+
+
+
+# A "regular expression" printer which conforms to the
+# "SubPrettyPrinter" protocol from gdb.printing.
+class RxPrinter(object):
+    def __init__(self, name, function):
+        super(RxPrinter, self).__init__()
+        self.name = name
+        self.function = function
+        self.enabled = True
+
+    def invoke(self, value):
+        if not self.enabled:
+            return None
+        return self.function(self.name, value)
+
+
+# A pretty-printer that conforms to the "PrettyPrinter" protocol from
+# gdb.printing.  It can also be used directly as an old-style printer.
+class Printer(object):
+    def __init__(self, name):
+        super(Printer, self).__init__()
+        self.name = name
+        self.subprinters = []('vec_size'])))
+        self.lookup = {}
+        self.enabled = True
+        self.compiled_rx = re.compile('^([def add(self, name, function):
+        1. A small sanity check.
+        1. FIXME
+        if not self.compiled_rx.match(name + '<>'):
+            raise ValueError, 'libstdc++ programming error: "%s" does not match' % name
+        printer = RxPrinter(name, function)
+        self.subprinters.append(printer)
+        self.lookup[name](a-zA-Z0-9_:]+)<.*>$')) = printer
+
+    @staticmethod
+    def get_basic_type(type):
+        1. If it points to a reference, get the reference.
+        if type.code == gdb.TYPE_CODE_REF:
+            type = type.target ()
+
+        1. Get the unqualified type, stripped of typedefs.
+        type = type.unqualified ().strip_typedefs ()
+
+        return type.tag
+
+    def __call__(self, val):
+        typename = self.get_basic_type(val.type)
+        if not typename:
+            return None
+
+        1. All the types we match are template types, so we can use a
+        1. dictionary.
+        match = self.compiled_rx.match(typename)
+        if not match:
+            return None
+
+        basename = match.group(1)
+        if basename in self.lookup:
+            return self.lookup[basename].invoke(val)
+
+        1. Cannot find a pretty printer.  Return None.
+        return None
+
+dealii_printer = None
+
+def build_dealii_dictionary ():
+    global dealii_printer
+
+    dealii_printer = Printer("deal.II")
+    dealii_printer.add ('dealii::Point', PointPrinter)
+    dealii_printer.add ('dealii::Tensor', TensorPrinter)
+    dealii_printer.add ('dealii::TriaRawIterator', TriaIteratorPrinter)
+    dealii_printer.add ('dealii::TriaIterator', TriaIteratorPrinter)
+    dealii_printer.add ('dealii::TriaActiveIterator', TriaIteratorPrinter)
+    dealii_printer.add ('dealii::Vector', VectorPrinter)
+
+def register_dealii_printers (obj):
+    "Register deal.II pretty-printers with objfile Obj."
+
+    global _use_gdb_pp
+    global dealii_printer
+
+    build_dealii_dictionary ()
+    if _use_gdb_pp:
+        gdb.printing.register_pretty_printer(obj, dealii_printer)
+    else:
+        if obj is None:
+            obj = gdb
+        obj.pretty_printers.append(dealii_printer)
+
+
+register_dealii_printers (None)
+
+end
+```
diff --git a/ealii-Users-Worldwide.md b/ealii-Users-Worldwide.md
new file mode 100644 (file)
index 0000000..13e3561
--- /dev/null
@@ -0,0 +1,76 @@
+# People who are actively using deal.II around the world and what they do
+
+# List of researchers, groups and centers using deal.II
+
+## Canada
+
+  === [University of Alberta](http://www.ualberta.ca), Edmonton ===
+  Prof. Marc Secanell Gallart at [ESDL](http://www.mece.ualberta.ca/groups/energysystemsdesign/) (Energy Systems Design Lab) and his group
+    - Fuel cell simulations
+
+  
+
+## Germany
+
+  === [Georg-August-Universität Göttingen](http://www.uni-goettingen.de/) ===
+
+  Researchers in Applied Mathematics associated with [Prof. Gert Lube](http://www.num.math.uni-goettingen.de/lube/); notably, Timo Heister joined the developer team from this group.
+    - Simulation and applications of turbulent flows
+    - Parallel computing
+
+  === [Helmut-Schmidt-Universität Universität der Bundeswehr Hamburg](http://www.hsu-hh.de/) ===
+
+  [Prof. Markus Bause](http://www.hsu-hh.de/mb-mathe/index_8Nk2UtXjFq8mxHBX.html) and his team
+    - wave propagation
+    - composite materials
+    - approximation
+
+  === [Ruprecht-Karls-Universität Heidelberg](http://www.uni-heidelberg.de/) ===
+
+  [Prof. Guido Kanschat](http://www.iwr.uni-heidelberg.de/groups/MathSim) and Natasha Sharma at the [IWR](http://www,iwr.uni-heidelberg.de) (Interdisziplinäres Zentrum für Wissenschaftliches Rechnen)
+    - coupled free and porous media flow
+    - radiative transfer
+    - computational electromagnetics
+    - multigrid methods and adaptivity
+
+   Thomas Carraro, Matthias Maier and others associated with the chair for [Numerical Analysis](http://numerik.uni-hd.de/) of Prof. Rolf Rannacher
+    - Parameter estimation for PDE
+    - Shape optimization
+
+  === [Universität Siegen](http://www.uni-siegen.de/start/) ===
+  [Arbeitsgruppe Wissenschaftliches Rechnen](http://www.uni-siegen.de/fb6/wir/index.html), Prof. Franz-Theo Suttmeier
+    - Solid materials
+
+  Lehrstuhl für Strömungsmechanik, Prof. Dr.-Ing. Foysi
+    - Fluid-structure interaction
+
+## Italy
+
+  === [Scuola Internazionale Superiore di Studi Avanzati](http://www.sissa.it), Trieste ===
+
+  [Prof. Luca Heltai](http://people.sissa.it/~heltai/) uses deal.II for
+    - Hydrodynamical problems in industrial projects related to ocean navigation [- biomedical applications
+    - immersed boundary methods
+
+## Republic of South Africa
+
+  === [http://www.uct.ac.za/ University of Cape Town](http://www.openship.it/]) ===
+  Dr. Andrew McBride and others at [CERECAM](http://www.cerecam.uct.ac.za/) (Centre for Research in Computational and Applied Mechanics)
+    - Nonlinear thermomechanics
+    - Crystal plasticity
+    - DG methods for problems in elasticity
+    - Low-order finite element simulation of generalized Oldroyd-B model
+
+## United States of America
+
+  === [Texas A&M University](http://www.math.tamu.edu/research/numerical_analysis/) ===
+
+  Most of the graduate student research in the entire numerical analysis group at Texas A&M's Department of Mathematics is built on deal.II. Dr. Wolfgang Bangerth teaches a scientific computing class on deal.II every other year.
+
+  === [University of California, Davis](https://www.geology.ucdavis.edu/) ===
+
+  The groups of [Louise Kellogg](http://mygeologypage.ucdavis.edu/kellogg/) and [Magali Billen](http://mygeologypage.ucdavis.edu/billen/) at the Department of Geology are using [ASPECT](http://www.dealii.org/aspect), a code for the simulation of convection in the earth mantle.
+
+  === [University of California, Berkeley](http://eps.berkeley.edu/people/faculty.php) ===
+
+  The groups of [Bruce Buffett](http://eps.berkeley.edu/development/view_person.php?uid=326008) and [Mark Richards](http://eps.berkeley.edu/development/view_person.php?uid=7517) are also using the ASPECT code mentioned above.
\ No newline at end of file
diff --git a/macs.md b/macs.md
new file mode 100644 (file)
index 0000000..8509ead
--- /dev/null
+++ b/macs.md
@@ -0,0 +1,108 @@
+# Notes on using emacs for deal.II
+
+# Introduction
+
+Emacs used to be the tool most of the deal.II developers worked with day in and day out. However, this has more to do with the fact that these people started to use computers in the late 1980s and early 1990s when emacs was a state-of-the-art editor. This is no longer the case, and so we have moved on. The purpose of this site is simply to present the set of emacs macros that have been used to format most of the deal.II source code.
+
+If you want to use this style and you still happen to use emacs then the following emacs elisp macros are for you:
+
+```
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;;
+;; Emacs macros supporting deal.II programming
+;;
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+
+(defun deal-indentation ()
+"Install the indentation offsets used in the deal.II source code.
+All contributions to the library should follow this indentation in
+order to maintain a common look and feel as well as avoiding
+unnecessary diffs in the archives.
+
+The function is intended as a part of the cc-mode-startup-fun hook."
+
+  (setq c-echo-semantic-information-p t)
+  (setq c-basic-offset 2)
+  (c-set-offset 'string                0)
+  (c-set-offset 'defun-open            0)
+  (c-set-offset 'defun-close           0)
+  (c-set-offset 'defun-block-intro     '+)
+  (c-set-offset 'class-open            0)
+  (c-set-offset 'class-close           0)
+  (c-set-offset 'inline-open           '+)
+  (c-set-offset 'inline-close          0)
+  (c-set-offset 'knr-argdecl-intro     '+)
+  (c-set-offset 'knr-argdecl           0)
+  (c-set-offset 'topmost-intro         0)
+  (c-set-offset 'topmost-intro-cont    0)
+  (c-set-offset 'member-init-intro     16)
+  (c-set-offset 'member-init-cont      0)
+  (c-set-offset 'inher-intro           '+)
+  (c-set-offset 'inher-cont            'c-lineup-multi-inher)
+  (c-set-offset 'block-close           0)
+  (c-set-offset 'brace-list-open       0)
+  (c-set-offset 'brace-list-close      0)
+  (c-set-offset 'brace-list-intro      6)
+  (c-set-offset 'brace-list-entry      0)
+  (c-set-offset 'statement             'c-lineup-runin-statements)
+  (c-set-offset 'statement-cont        'c-lineup-math)
+  (c-set-offset 'statement-block-intro '+)
+  (c-set-offset 'statement-case-intro  6)
+  (c-set-offset 'statement-case-open   0)
+  (c-set-offset 'substatement          '+)
+  (c-set-offset 'substatement-open     '+)
+  (c-set-offset 'case-label            '+)
+  (c-set-offset 'access-label          '-)
+  (c-set-offset 'label                 2)
+  (c-set-offset 'do-while-closure      0)
+  (c-set-offset 'else-clause           0)
+  (c-set-offset 'arglist-intro         '+)
+  (c-set-offset 'arglist-cont          0)
+  (c-set-offset 'arglist-cont-nonempty 'c-lineup-arglist)
+  (c-set-offset 'arglist-close         0)
+  (c-set-offset 'stream-op             'c-lineup-streamop)
+  (c-set-offset 'inclass               '++)
+  (c-set-offset 'cpp-macro             -1000)
+  (c-set-offset 'friend                0)
+
+  (c-set-offset 'comment-intro         'c-lineup-comment)
+  (c-set-offset 'c                     'c-lineup-C-comments)
+  
+  (c-set-offset 'objc-method-intro     -1000)
+  (c-set-offset 'objc-method-args-cont 'c-lineup-ObjC-method-args)
+  (c-set-offset 'objc-method-call-cont 'c-lineup-ObjC-method-call)
+       
+  (setq c-comment-only-line-offset 33)
+  (setq c-hanging-comment-ender-p   nil)
+  (setq c-hanging-comment-starter-p nil)
+
+  (setq c-tab-always-indent t)
+)
+
+(defun deal-newline ()
+"Setup emacs to automatically insert newlines and indentation before
+and after semicolon or braces, like it is done in the deal.II coding style."
+  (define-key c++-mode-map "\C-m" 'newline-and-indent)
+  (setq c-hanging-braces-alist '((defun-open        . (before after))
+                                 (defun-close       . (before after))
+                                 (class-open        . (before after))
+                                 (class-close       . (after))
+                                 (inline-open       . (before after))
+                                 (inline-close      . (before after))
+                                 (block-open        . (before after))
+                                 (block-close       . (after))
+                                 (brace-list-open   . (nil))))
+  (setq c-hanging-colons-alist '((member-init-intro . (after))
+                                (inher-intro       . (after))
+                                (label             . (after))
+                                (case-label        . (after))
+                                (access-label      . (after))))
+  (setq c-cleanup-list '(empty-defun-braces
+                        defun-close-semi
+                        list-close-comma
+                        scope-operator))
+  (setq c-default-macroize-column 65)
+)
+
+(provide 'dealmacros)
+```

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.