From 08074467983bc0bd3c02d1c21ee92a1d424613a5 Mon Sep 17 00:00:00 2001 From: Wolfgang Bangerth Date: Sat, 11 May 2024 08:08:27 -0600 Subject: [PATCH] Better describe the equivalence triangulation=mesh=grid. --- examples/step-1/doc/intro.dox | 62 ++++++++++++++++++++++++++--------- include/deal.II/grid/tria.h | 10 +++--- 2 files changed, 51 insertions(+), 21 deletions(-) diff --git a/examples/step-1/doc/intro.dox b/examples/step-1/doc/intro.dox index 5476846141..d164a9cac6 100644 --- a/examples/step-1/doc/intro.dox +++ b/examples/step-1/doc/intro.dox @@ -17,7 +17,7 @@ different levels: 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 means, + argument of Triangulation::create_triangulation() means, to give just one 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 @@ -40,7 +40,7 @@ different levels: 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 + Triangulation, you 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. @@ -137,22 +137,52 @@ later on. Additionally, as of deal.II version 9.0, GridGenerator::hyper_shell() now automatically attaches a SphericalManifold to the Triangulation. Otherwise the rest of the lecture material is relevant. +

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). +Let's come back to step-1, the current program. The goal of this +program is to introduce you to the Triangulation class that is at the +core of every finite element program. The name "triangulation" in this +context is mostly historical: To finite element practitioners, the +terms "triangulation", "mesh", and "grid" are all synonymous and +describe a subdivision of a domain on which a differential equation is +posed into cells of some kind. If the domain is two-dimensional, these +cells may indeed be triangles, but they could also be quadrilaterals +(four-sided objects such as squares and rectangles, and their +deformations). In one space dimension, the cells are line segments. In +three space dimensions, they can be tetrahedra, hexahedra (deformed +cubes), pyramids (a four-sided base with three triangles connecting to +a point at the top), and "wedges" (two triangles at the bottom and +top, connected by three quadrilaterals; wedges are often also called +"(triangular) prisms", for example in +[this wikipedia article about types of meshes](https://en.wikipedia.org/wiki/Types_of_mesh)). +Collections of any such cells are +"triangulations" in common usage of the word even though they may not +actually have triangles in them. All of them are also "grids" in +common usage of the word even though the usual meaning of the word "grid" +would be something where the vertices are in neat rows +parallel to the coordinate axes (which would then be a "structured grid" +in the finite element context). In other words, whenever you read any +of the three terms in the tutorials or the library's documentation, +consider them equivalent. + +What this program shows, then, is how to create a Triangulation +object, and to operate on it. The underlying concept of a +Triangulation is that it is a *container*, i.e., a class that stores a +*collection of cells*. As is common in modern programming languages, +the key operation on containers is that one can *iterate* over its +elements, and that's exactly what we will do below. + +Specifically, in the program we create two grids, one which is a +regularly refined square (not very exciting, but a common starting +grid for many problems), and one that is a more geometric attempt: a +ring-shaped domain that is refined towards the inner edge. The process +of refining the mesh in this way will illustrate how we iterate (i.e., +loop) over the elements of the triangulation (i.e., the cells of the +mesh). You will see many more such loops throughout the remainder +of the tutorial. (Since there are so many loops over cells in finite +element programs, the @ref Iterators module talks about them in more +detail.) The program is otherwise small enough that it doesn't need a whole lot of introduction. diff --git a/include/deal.II/grid/tria.h b/include/deal.II/grid/tria.h index 1445fdcbf0..d92c8ff735 100644 --- a/include/deal.II/grid/tria.h +++ b/include/deal.II/grid/tria.h @@ -550,12 +550,12 @@ namespace internal * associated with curves in 2d or surfaces in 3d) are the ones one wants to * use in the boundary element method. * - * The name of the class is mostly hierarchical and is not meant to imply that + * The name of the class is mostly historical and is not meant to imply that * a Triangulation can only consist of triangles. Instead, triangulations - * consist of line segments in 1d (i.e., if `dim==1`), and of three-dimensional - * cells (if `dim==3`). Moreover, historically, deal.II only supported - * quadrilaterals (cells with four vertices: deformed rectangles) in 2d - * and hexahedra (cells with six sides and eight vertices that are deformed + * will consist of line segments in 1d (i.e., if `dim==1`), and of + * three-dimensional cells (if `dim==3`). Moreover, historically, deal.II only + * supported quadrilaterals (cells with four vertices: deformed rectangles) in + * 2d and hexahedra (cells with six sides and eight vertices that are deformed * boxes), neither of which are triangles. In other words, the term * "triangulation" in the deal.II language is synonymous with "mesh" and is * to be understood separate from its linguistic origin. -- 2.39.5