From: heister Date: Mon, 4 Feb 2013 17:20:49 +0000 (+0000) Subject: step-49: add images, write down notes X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=4d85c1cbb395d248079f24864a4991387713c3d8;p=dealii-svn.git step-49: add images, write down notes git-svn-id: https://svn.dealii.org/trunk@28221 0785d39b-7218-0410-832d-ea1e28bc413d --- diff --git a/deal.II/examples/step-49/doc/builds-on b/deal.II/examples/step-49/doc/builds-on index 8b13789179..4512741e57 100644 --- a/deal.II/examples/step-49/doc/builds-on +++ b/deal.II/examples/step-49/doc/builds-on @@ -1 +1 @@ - +step-1 diff --git a/deal.II/examples/step-49/doc/gmsh_picture.png b/deal.II/examples/step-49/doc/gmsh_picture.png new file mode 100644 index 0000000000..a24e14857c Binary files /dev/null and b/deal.II/examples/step-49/doc/gmsh_picture.png differ diff --git a/deal.II/examples/step-49/doc/intro.dox b/deal.II/examples/step-49/doc/intro.dox index c3629d2973..1cc78d1989 100644 --- a/deal.II/examples/step-49/doc/intro.dox +++ b/deal.II/examples/step-49/doc/intro.dox @@ -1,157 +1,70 @@

Introduction

-

About the tutorial

- -Since this is the first tutorial program, let us comment first on how -this tutorial and the rest of the deal.II documentation is supposed to -work. The documentation for deal.II comes essentially at three -different levels: -- The tutorial: This is a collection of programs that shows how - deal.II is used in practice. It doesn't typically discuss individual - functions at the level of individual arguments, but rather wants to - give the big picture of how things work together. In other words, it - discusses "concepts": what are the building blocks of deal.II and - how are they used together in finite element programs. -- The manual: This is the documentation of every single class and - every single (member) function in deal.II. You get there if, for - example, you click on the "Main page" or "Classes" tab at the top of - this page. This is the place where you would look up what the second - argument of Triangulation::create_triangulation_compatibility means, - to give just one slightly obscure example. You need this level of - documentation for when you know what you want to do, but forgot how - exactly the function was named, what its arguments are, or what it - returns. Note that you also get into the manual whenever you read - through the tutorial and click on any of the class or function - names, i.e. the tutorial contains a great many links into the manual - for whenever you need a more detailed description of a function or - class. On the other hand, the manual is not a good place to learn - deal.II since it gives you a microscopic view of things without - telling you how a function might fit into the bigger picture. -- Modules: These are groups of classes and functions that work - together or have related functionality. If you click on the - "Modules" tab at the top of this page, you end up on a page that - lists a number of such groups. Each module discusses the underlying - principles of these classes; for example, the @ref Sparsity module - talks about all sorts of different issues related to storing - sparsity patterns of matrices. This is documentation at an - intermediate level: they give you an overview of what's there in a - particular area. For example when you wonder what finite element - classes exist, you would take a look at the @ref fe module. The - modules are, of course, also cross-linked to the manual (and, at - times, to the tutorial); if you click on a class name, say on - Triangulation, would will also at the very top right under the class - name get a link to the modules this class is a member of if you want - to learn more about its context. - -Let's come back to the tutorial, since you are looking at the first program -(or "step") of it. Each tutorial program is subdivided into the following -sections: -
    -
  1. Introduction: This is a discussion of what the program - does, including the mathematical model, and - what programming techniques are new compared to previous - tutorial programs. -
  2. The commented program: An extensively documented listing of the - source code. Here, we often document individual lines, or - blocks of code, and discuss what they do, how they do it, and - why. The comments frequently reference the introduction, - i.e. you have to understand what the program wants to achieve - (a goal discussed in the introduction) before you can - understand how it intends to get there. -
  3. Results: The output of the program, with comments and - interpretation. This section also frequently has a subsection - that gives suggestions on how to extend the program in various - direction; in the earlier programs, this is intended to give - you directions for little experiments designed to make your - familiar with deal.II, while in later programs it is more about - how to use more advanced numerical techniques. -
  4. The plain program: The source code stripped of - all comments. This is useful if you want to see the "big - picture" of the code, since the commented version of the - program has so much text in between that it is often difficult - to see the entire code of a single function on the screen at - once. -
- -The tutorials are not only meant to be static documentation, but you -should play with them. To this end, go to the -examples/step-1 directory (or whatever the number of the -tutorial is that you're interested in) and type -@code - make - make run -@endcode -The first command compiles the sources into an executable, while the -second executes it (strictly speaking, make run will also -compile the code if the executable doesn't exist yet, so you could -have skipped the first command if you wanted). This is all that's -needed to run the code and produce the output that is discussed in the -"Results" section of the tutorial programs. - -When learning the library, you need to play with it and see what -happens. To this end, open the examples/step-1/step-1.cc -source file with your favorite editor and modify it in some way, save it and -run it as above. A few suggestions for possibly modifications are given at the -end of the results section of this program, where we also provide a few links -to other useful pieces of information. - - -

What this program does

- -Let's come back to step-1, the current program. -In this first example, we don't actually do very much, but show two -techniques: what is the syntax to generate triangulation objects, and -some elements of simple loops over all cells. We create two grids, one -which is a regularly refined square (not very exciting, but a common -starting grid for some problems), and one more geometric attempt: a -ring-shaped domain, which is refined towards the inner edge. Through -this, you will get to know three things every finite element program -will have to have somewhere: An object of type Triangulation for the -mesh; a call to the GridGenerator functions to generate a mesh; and -loops over all cells that involve iterators (iterators are a -generalization of pointers and are frequently used in the C++ standard -library; in the context of deal.II, the @ref Iterators module talks -about them). - -The program is otherwise small enough that it doesn't need a whole lot -of introduction. Let us just continue with its commented source. - - -

About scientific computing in general

- -If you are reading through this tutorial program, chances are that you are -interested in continuing to use deal.II for your own projects. Thus, you are -about to embark on an exercise in programming using a large-scale scientific -computing library. Unless you are already an experienced user of large-scale -programming methods, this may be new territory for you — with all the -new rules that go along with it such as the fact that you will have to deal -with code written by others, that you may have to think about documenting your -own code because you may not remember what exactly it is doing a year down the -road (or because others will be using it as well), or coming up with ways to -test that your program is doing the right thing. None of this is something -that we typically train mathematicians, engineers, or scientists in but that -is important when you start writing software of more than a few hundred -lines. Remember: Producing software is not the same as just writing code. - -To make your life easier on this journey let us point to two resources that -are worthwhile browsing through before you start any large-scale programming: - -- The deal.II - Frequently Asked Questions: This page has a good number of questions - that pertain to particular aspects of deal.II, but also to more general - questions such as "How do I debug scientific computing codes?" or "Can I - train myself to write code that has fewer bugs?". - -- The Software Carpentry project - that provides introductions to many topics that are important to dealing - with software, such as version control, make files, testing, etc. It is - specifically written for scientists and engineers, not for computer - scientists, and has a focus on short, practical lessons. - -As a general recommendation: If you expect to spend more than a few days -writing software in the future, do yourself the favor of learning tools that -can make your life more productive, in particular debuggers and integrated -development environments. You will find that you will get the time spent -learning these tools back severalfold soon by being more productive! +

About this tutorial

+ +intro: +- complex geometries +- this is challenging +- some solutions here + +What this program does: +- make/modify meshes +- output them +- nothing else + +

How to create meshes

+ +

GridGenerator

+use GridGenerator (already discussed in step-1) + +examples: hyper_cube, hyper_shell, ... + +

construct your own mesh programmatically

+ +example? + +

Import from external programs

+ +import mesh from file, read using GridIn + +list of tools: cubeit, gmsh, more? +problem: need to generate quads + +- how to use gmsh + - 2d + - 3d: mention difficulties + + +gmsh: +use physical lines/surfaces + +this is how it looks like in gmsh: +@image html gmsh_picture.png + + + +this is the mesh read from gmsh: +@image html step-49.grid-1.png + + +

Modify a Mesh

+ +modify a mesh: + - merge meshes + - change boundary indicators + - move vertices + - transform via smooth function + - perturb mesh + +

Merge Meshes

+ +note, vertices have to match exactly. + +@image html step-49.grid-2.png + + +

Move Vertices

+ +@image html step-49.grid-3.png + diff --git a/deal.II/examples/step-49/doc/results.dox b/deal.II/examples/step-49/doc/results.dox index 595a388fa6..675d2d5305 100644 --- a/deal.II/examples/step-49/doc/results.dox +++ b/deal.II/examples/step-49/doc/results.dox @@ -15,65 +15,6 @@ like this: -The left one, well, is not very exciting. The right one is — at least -— unconventional. - -While the second mesh is entirely artificial and made-up, and -certainly not very practical in applications, to everyone's surprise it -has found its way into the literature: see the paper by M. Mu -titled "PDE.MART: A network-based problem-solving environment", ACM -Trans. Math. Software, vol. 31, pp. 508-531, 2005. Apparently it is -good for some things at least. -

Possible extensions

-

Different adaptive refinement strategies

- -This program obviously does not have a whole lot of functionality, but -in particular the second_grid function has a bunch of -places where you can play with it. For example, you could modify the -criterion by which we decide which cells to refine. An example would -be to change the condition to this: -@code - for (; cell!=endc; ++cell) - if (cell->center()[1] > 0) - cell->set_refine_flag (); -@endcode -This would refine all cells for which the $y$-coordinate of the cell's -center is greater than zero (the TriaAccessor::center -function that we call by dereferencing the cell iterator -returns a Point<2> object; subscripting [0] would give -the $x$-coordinate, subscripting [1] the -$y$-coordinate). By looking at the functions that TriaAccessor -provides, you can also use more complicated criteria for refinement. - -

Different geometries

- -Another possibility would be to generate meshes of entirely different -geometries altogether. While for complex geometries there is no way around -using meshes obtained from mesh generators, there is a good number of -geometries for which deal.II can create meshes using the functions in the -GridGenerator namespace. Take a look at what it provides and see how it could -be used in a program like this. - -

Comments about programming and debugging

- -We close with a comment about modifying or writing programs with deal.II in -general. When you start working with tutorial programs or your own -applications, you will find that mistakes happen: your program will contain -code that either aborts the program right away or bugs that simply lead to -wrong results. In either case, you will find it extremely helpful to know how -to work with a debugger: 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. - -Rather than postponing learning how to use a debugger till you really can't -see any other way to find a bug, here's the one piece of -advice we will provide in this program: learn how to use a debugger as soon as -possible. It will be time well invested. The deal.II Frequently Asked -Questions (FAQ) page linked to from the top-level deal.II webpage also provides a good number -of hints on debugging deal.II programs. diff --git a/deal.II/examples/step-49/doc/step-49.grid-1.png b/deal.II/examples/step-49/doc/step-49.grid-1.png new file mode 100644 index 0000000000..ba6920e712 Binary files /dev/null and b/deal.II/examples/step-49/doc/step-49.grid-1.png differ diff --git a/deal.II/examples/step-49/doc/step-49.grid-2.png b/deal.II/examples/step-49/doc/step-49.grid-2.png new file mode 100644 index 0000000000..19bee01464 Binary files /dev/null and b/deal.II/examples/step-49/doc/step-49.grid-2.png differ diff --git a/deal.II/examples/step-49/doc/step-49.grid-3.png b/deal.II/examples/step-49/doc/step-49.grid-3.png new file mode 100644 index 0000000000..f2e9cfb805 Binary files /dev/null and b/deal.II/examples/step-49/doc/step-49.grid-3.png differ