]> https://gitweb.dealii.org/ - dealii-svn.git/commitdiff
put documentation of functions into documentation of functions
authorkanschat <kanschat@0785d39b-7218-0410-832d-ea1e28bc413d>
Fri, 8 Jun 2007 03:08:55 +0000 (03:08 +0000)
committerkanschat <kanschat@0785d39b-7218-0410-832d-ea1e28bc413d>
Fri, 8 Jun 2007 03:08:55 +0000 (03:08 +0000)
git-svn-id: https://svn.dealii.org/trunk@14769 0785d39b-7218-0410-832d-ea1e28bc413d

deal.II/deal.II/include/grid/grid_generator.h
deal.II/doc/doxygen/images/hypershell3d-12.png [moved from deal.II/doc/pictures/hypershell3d-12.png with 100% similarity]
deal.II/doc/doxygen/images/hypershell3d-6.png [moved from deal.II/doc/pictures/hypershell3d-6.png with 100% similarity]

index 793575b2e9e08f2cb110d3188b138ea4f87a0f22..b28fe3e837aa609b3d029b7c7d2162226415fd56 100644 (file)
@@ -28,106 +28,9 @@ template <typename number> class SparseMatrix;
 
 
 /**
- * This class offers triangulations of some standard domains such as hypercubes,
- * hyperball and the like. Following is a list of domains that can be generated
- * by the functions of this class:
- * <ul>
- *    <li> Hypercube:
- *       the GridGenerator::hyper_cube function produces the unit line
- *       segment, unit square, or unit cube:
- *
- *      @image html hyper_cubes.png
- * 
- *    <li> Generalized L-shape domain:
- *      using the GridGenerator::hyper_L (tria, a,b) function produces
- *      the hypercube with the interval $[a,b]$ without the hypercube
- *      made out of the interval $[(a+b)/2,b]$. Let, for example, be $a=-1$
- *      and $b=1$, then the hpyer-L in two dimensions is the region
- *      $[-1,1]^2 - [0,1]^2$. To create a hyper-L in one dimension results in
- *      an error. The function is also implemented for three space dimensions
- *      and produces the following domain (not completely to scale, the
- *      cut-out part should have exactly half the edge length of the entire
- *      cube):
- *
- *      @image html hyper_l.png
- *
- *    <li> Hyper ball:
- *      You get the circle or ball (or generalized: hyperball) around
- *      origin @p p and with radius @p r by calling
- *      GridGenerator::hyper_ball (tria, p, r). The circle is
- *      triangulated by five cells, the ball by seven cells. The
- *      diameter of the center cell is chosen so that the aspect ratio
- *      of the boundary cells after one refinement is minimized in
- *      some way. To create a hyperball in one dimension results in an
- *      error.
- *
- *      Do not forget to also attach a suitable boundary approximation object
- *      to the triangulation object you passed to this function if you later want
- *      the triangulation to be refined at the outer boundaries.
- *
- *    <li> Half Hyper ball:
- *      You get half of the circle or sphere generated by Hyper ball.
- *      with center @p p and with radius @p r by calling
- *      GridGenerator::half_hyper_ball (tria, p, r). The half-circle is 
- *      triangulated by four cells, while the half-sphere is triangulated by
- *     six cells. The diameter of the center cell is
- *      chosen to be the same as for the Hyper ball class. 
- *      To create a half-hyperball in one dimension results in
- *      an error.
- *
- *      Do not forget to also attach a suitable boundary approximation object
- *      to the triangulation object you passed to this function if you later want
- *      the triangulation to be refined at the outer boundaries. Both classes
- *      HalfHyperBallBoundary and HyperBallBoundary will provide a valid 
- *     boundary object.
- *
- *    <li> Hyper shell: A hyper shell is the region between two hyper
- *      sphere with the same origin. Therefore, it is a ring in two
- *      spatial dimensions. To triangulation it, call the function
- *      GridGenerator::hyper_shell (tria, origin, inner_radius, outer_radius, N),
- *      where the center of the spheres as well as
- *      the inner and outer radius of the two spheres are given as
- *      shown.
- *
- *      The parameter @p N denotes how many cells are to be used for
- *      this coarse triangulation. It defaults to zero, which tells
- *      the function to chose the number itself; this, then, is done
- *      such that the aspect ration of the resulting cells is as small
- *      as possible. However, it should be mentioned that this
- *      function does not work very well if the inner radius is much
- *      smaller than the outer radius since only one layer of cells is
- *      used in the radial direction.
- *
- *      You need to attach a boundary object to the triangulation. A
- *      suitable boundary class is provided as HyperSphereBoundary
- *      in the library.
- *
- *    <li> Half shells: This is a variant of the preceding domain,
- *      where only one half of the shell is taken, defined by the first
- *      coordinate having non-negative values. This class is useful in
- *      computations with rotational symmetry, as then a 3d shell can be
- *      modeled by a 2d half shell.
- *
- *    <li> Slit domain: The slit domain is a variant of the hyper cube
- *      domain. In two spatial dimensions, it is a square into which a
- *      slit is sawed; if the initial square is though to be composed
- *      of four smaller squares, then two of them are not connected
- *      even though they are neighboring each other. Analogously, into
- *      the cube in three spatial dimensions, a half-plane is sawed,
- *      disconnecting four of the eight child-cubes from one of their
- *      neighbors.  
- * 
- *    <li> Hyper cube with cylindrical hole: This domain is a square on
- *      the xy plane times the interval [0,L] with a cylindrical hole
- *      in the middle. The parameters that can be set are the internal
- *      radius, the external radius (inteded as the radius of the
- *      biggest enclosed cylinder), the depth of the structure (used
- *      only in three dimensions), and the number of repetitions along
- *      the z direction.
- *
- *      @image html cubes_hole.png
- *      
- * </ul>
+ * This class provides a collection of functions for generating basic
+ * triangulations. Below, we try to provide some pictures in order to
+ * illustrate at least the more complex ones.
  *
  * Some of these functions receive a flag @p colorize. If this is
  * set, parts of the boundary receive different boundary numbers,
@@ -141,7 +44,9 @@ template <typename number> class SparseMatrix;
  * shell onto a grid of an airfoil, for example.
  *
  * @ingroup grid
- * @author Wolfgang Bangerth, Ralf Hartmann, Guido Kanschat, Stefan Nauber, Joerg Weimar, Yaqi Wang, 1998, 1999, 2000, 2001, 2002, 2003, 2006.
+ * @author Wolfgang Bangerth, Ralf Hartmann, Guido Kanschat, Stefan
+ * Nauber, Joerg Weimar, Yaqi Wang, 1998, 1999, 2000, 2001, 2002,
+ * 2003, 2006, 2007.
  */
 class GridGenerator
 {
@@ -161,6 +66,8 @@ class GridGenerator
                                      * then producing the unit
                                      * hypercube.
                                      *
+                                     * @image html hyper_cubes.png
+                                     *
                                      * See also
                                      * subdivided_hyper_cube() for a
                                      * coarse mesh consisting of
@@ -406,16 +313,18 @@ class GridGenerator
                                      * Initialize the given
                                      * triangulation with a
                                      * hyperball, i.e. a circle or a
-                                     * ball.  See the general
-                                     * documentation for a more
-                                     * concise description. The
-                                     * center of the hyperball
-                                     * default to the origin, the
-                                     * radius defaults to unity.
-                                     *
-                                     * The triangulation needs to be
-                                     * void upon calling this
-                                     * function.
+                                     * ball around <tt>center</tt>
+                                     * with given <tt>radius</tt>.
+                                     *
+                                     * In order to avoid degenerate
+                                     * cells at the boundaries, the
+                                     * circle is triangulated by five
+                                     * cells, the ball by seven
+                                     * cells. The diameter of the
+                                     * center cell is chosen so that
+                                     * the aspect ratio of the
+                                     * boundary cells after one
+                                     * refinement is optimized.
                                      *
                                      * This function is declared to
                                      * exist for triangulations of
@@ -432,6 +341,32 @@ class GridGenerator
                            const Point<dim>   &center = Point<dim>(),
                            const double      radius = 1.);
 
+                                    /**
+                                     * This class produces a half
+                                     * hyper-ball around
+                                     * <tt>center</tt>, which
+                                     * contains four elements in 2d
+                                     * and 6 in 3d. The cut plane is
+                                     * perpendicular to the
+                                     * <i>x</i>-axis.
+                                     *
+                                     * The boundary indicators for the final 
+                                     * triangulation are 0 for the curved boundary and
+                                     * 1 for the cut plane. 
+                                     *
+                                     * The appropriate
+                                     * boundary class is 
+                                     * HalfHyperBallBoundary, or HyperBallBoundary.
+                                     * 
+                                     * @note The triangulation needs to be
+                                     * void upon calling this
+                                     * function.
+                                     */
+    template <int dim>
+    static void half_hyper_ball (Triangulation<dim> &tria,
+                                const Point<dim>   &center = Point<dim>(),
+                                const double      radius = 1.);
+
                                     /**
                                      * Create a cylinder around the
                                      * x-axis.  The cylinder extends
@@ -468,11 +403,13 @@ class GridGenerator
                                      * Initialize the given
                                      * triangulation with a hyper-L
                                      * consisting of exactly
-                                     * <tt>2^dim-1</tt> cells. See the
-                                     * general documentation for a
-                                     * description of the
-                                     * L-region. The limits default
-                                     * to minus unity and unity.
+                                     * <tt>2^dim-1</tt> cells. It
+                                     * produces the hypercube with
+                                     * the interval [<i>left,right</i>] without
+                                     * the hypercube made out of the
+                                     * interval [<i>(a+b)/2,b</i>].
+                                     *
+                                     * @image html hyper_l.png
                                      *
                                      * The triangulation needs to be
                                      * void upon calling this
@@ -532,23 +469,30 @@ class GridGenerator
     
                                     /**
                                      * Produce a hyper-shell,
-                                     * i.e. the space between two
-                                     * circles in two space
-                                     * dimensions and the region
-                                     * between two spheres in 3d,
-                                     * with given inner and outer
-                                     * radius and a given number of
-                                     * elements for this initial
-                                     * triangulation. If the number
-                                     * of initial cells is zero (as
-                                     * is the default), then it is
-                                     * computed adaptively such that
-                                     * the resulting elements have
-                                     * the least aspect ratio.
-                                     *
-                                     * The triangulation needs to be
-                                     * void upon calling this
-                                     * function.
+                                     * the region between two
+                                     * spheres around <tt>center</tt>,
+                                     * with given
+                                     * <tt>inner_radius</tt> and
+                                     * <tt>outer_radius</tt>.
+                                     *
+                                     * In 2D, the number
+                                     * <tt>n_cells</tt> of elements
+                                     * for this initial triangulation
+                                     * can be chosen arbitrarily. If
+                                     * the number of initial cells is
+                                     * zero (as is the default), then
+                                     * it is computed adaptively such
+                                     * that the resulting elements
+                                     * have the least aspect ratio.
+                                     *
+                                     * In 3D, only two different
+                                     * numbers are meaningful, 6 for
+                                     * a surface based on a
+                                     * hexahedron and 12 for the
+                                     * rhombic dodecahedron.
+                                     *
+                                     * @image html hypershell3d-6.png
+                                     * @image html hypershell3d-12.png
                                      *
                                      * This function is declared to
                                      * exist for triangulations of
@@ -568,63 +512,6 @@ class GridGenerator
                             const double        outer_radius,
                             const unsigned int  n_cells = 0);
     
-                                    /**
-                                     * Produce a domain that is the space
-                                     * between two cylinders in 3d, with
-                                     * given length, inner and outer radius
-                                     * and a given number of elements for
-                                     * this initial triangulation. If @p
-                                     * n_radial_cells is zero (as is the
-                                     * default), then it is computed
-                                     * adaptively such that the resulting
-                                     * elements have the least aspect
-                                     * ratio. The same holds for @p
-                                     * n_axial_cells.
-                                     *
-                                     * @note Although this function
-                                     * is declared as a template, it
-                                     * does not make sense in 1D and
-                                     * 2D.
-                                     *
-                                     * @note The triangulation needs
-                                     * to be void upon calling this
-                                     * function.
-                                     */
-    template <int dim>
-    static void cylinder_shell (Triangulation<dim>   &tria,
-                                const double        length,
-                                const double        inner_radius,
-                                const double        outer_radius,
-                                const unsigned int  n_radial_cells = 0,
-                                const unsigned int  n_axial_cells = 0);
-
-                                    /**
-                                     * This class produces a half hyper-ball,
-                                     * which contains four elements in 2d and
-                                     * 6 in 3d. The orientation is such that 
-                                     * the cutting plane is the x=0.
-                                     *
-                                     * The triangulation needs to be
-                                     * void upon calling this
-                                     * function.
-                                     *
-                                     * The boundary indicators for the final 
-                                     * triangulation are 0 for the curved boundary and
-                                     * 1 for the cut plane. 
-                                     *
-                                     * The appropriate
-                                     * boundary class is 
-                                     * HalfHyperBallBoundary, or HyperBallBoundary.
-                                     * 
-                                     * @note The triangulation needs to be
-                                     * void upon calling this
-                                     * function.
-                                     */
-    template <int dim>
-    static void half_hyper_ball (Triangulation<dim> &tria,
-                                const Point<dim>   &center = Point<dim>(),
-                                const double      radius = 1.);
-
                                     /**
                                      * Produce a half hyper-shell,
                                      * i.e. the space between two
@@ -656,10 +543,6 @@ class GridGenerator
                                      * the resulting elements have
                                      * the least aspect ratio.
                                      *
-                                     * The triangulation needs to be
-                                     * void upon calling this
-                                     * function.
-                                     *
                                      * At present, this function only
                                      * exists in 2d.
                                      *
@@ -674,25 +557,59 @@ class GridGenerator
                                  const double        outer_radius,
                                  const unsigned int  n_cells = 0);
     
+                                    /**
+                                     * Produce a domain that is the space
+                                     * between two cylinders in 3d, with
+                                     * given length, inner and outer radius
+                                     * and a given number of elements for
+                                     * this initial triangulation. If @p
+                                     * n_radial_cells is zero (as is the
+                                     * default), then it is computed
+                                     * adaptively such that the resulting
+                                     * elements have the least aspect
+                                     * ratio. The same holds for @p
+                                     * n_axial_cells.
+                                     *
+                                     * @note Although this function
+                                     * is declared as a template, it
+                                     * does not make sense in 1D and
+                                     * 2D.
+                                     *
+                                     * @note The triangulation needs
+                                     * to be void upon calling this
+                                     * function.
+                                     */
+    template <int dim>
+    static void cylinder_shell (Triangulation<dim>   &tria,
+                                const double        length,
+                                const double        inner_radius,
+                                const double        outer_radius,
+                                const unsigned int  n_radial_cells = 0,
+                                const unsigned int  n_axial_cells = 0);
+
                                     /** 
                                      * This class produces a square
-                                     * on the @p xy-plane with a
+                                     * on the <i>xy</i>-plane with a
                                      * circular hole in the middle,
-                                     * times the interval @p [0.L]
-                                     * (only in 3d). It is
-                                     * implemented in 2d and 3d, and
-                                     * takes the following arguments:
+                                     * times the interval [0.L]
+                                     * (only in 3d).
+                                     *
+                                     *  @image html cubes_hole.png
+                                     *  
+                                     * It is implemented in 2d and
+                                     * 3d, and takes the following
+                                     * arguments:
                                      * 
-                                     * - @p inner_radius: size of the
+                                     * @arg @p inner_radius: size of the
                                       *    internal hole 
-                                     * - @p  outer_radius: size of the
+                                     * @arg @p  outer_radius: size of the
                                       *    biggest enclosed cylinder
-                                     * - @p L: extension on the @p z-direction
-                                     * - @p repetitions: number of subdivisions
+                                     * @arg @p L: extension on the @p z-direction
+                                     * @arg @p repetitions: number of subdivisions
                                      *      along the @p z-direction
-                                     * - @p colorize: wether to assign different 
+                                     * @arg @p colorize: wether to assign different 
                                      *     boundary indicators to different faces.
-                                     *    The colors are given in lexicografic 
+                                     *    The colors are given in lexicographic 
                                      *    ordering for the flat faces (0 to 3 in 2d, 
                                      *    0 to 5 in 3d) plus the curved hole 
                                      *    (4 in 2d, and 6 in 3d).

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.