diff --git a/doc/doxygen/example_simple.dox b/doc/doxygen/example_simple.dox index e69de29bb..43c41ebc2 100644 --- a/doc/doxygen/example_simple.dox +++ b/doc/doxygen/example_simple.dox @@ -0,0 +1,272 @@ +/* + This file is part of p4est. + p4est is a C library to manage a collection (a forest) of multiple + connected adaptive quadtrees or octrees in parallel. + + Copyright (C) 2010 The University of Texas System + Written by Carsten Burstedde, Lucas C. Wilcox, and Tobin Isaac + + p4est is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + p4est is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with p4est; if not, write to the Free Software Foundation, Inc., + 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +*/ + +/** \page example_simple Documentation for selected example programs + * + * The p4est library comes with various example programs. + * They are kept under the subdirectory + * [example](https://github.com/cburstedde/p4est/tree/master/example). + * Most have both a 2D and a 3D version. + * When the library is configured `--enable-mpi`, they can all be run in + * parallel on any number of MPI ranks, even on small computers. + * + * One first helpful program to try out is called `p4est_simple` (2D version) + * and `p8est_simple` (3D version), both under + * [simple](https://github.com/cburstedde/p4est/tree/master/example/simple). + * We showcase some results further below on this page, and we encourage + * everyone to play with the command line arguments. + * + * ### The first step example + * + * Quite some time later, we created a range of step-by-step examples under + * [steps](https://github.com/cburstedde/p4est/tree/master/example/steps). + * Let us begin here with the first one that generates a mesh spelling + * 'Hello, World!': \ref steps/p4est_step1.c. + * + * This program performs refinement on a simple domain based on hardcoded + * image data. + * As a result, the output VTK file displays the phrase 'Hello World' by the + * mesh refinement. + * + * Usage may be one of: + * + * > `p4est_step1` + * or with MPI: + * > `mpirun -np 3 p4est_step1` + * + * * No. of trees: 1 + * * Maximum refinement level: 6 + * + * \image html HW.png + * + * ### The historic simple example + * + * Another illustrative example can be found in \ref simple/simple2.c. + * The refinement pattern is generated by some hardcoded prescriptions based + * on a quadrant's tree number, refinement level and coordinates. + * Please see the documentation under that link for a full list of configurations. + * + * This program creates/refines & coarsens/balances/partitions one + * of several available geometries specified on the command line. + * As a result, the output VTK files document all + * the steps of the mesh manipulation process. + * + * * Example: periodic + * + * Create a connectivity structure for a periodic unit square. + * The left and right faces are identified, and bottom and top opposite. + * + * Usage: + * > `p4est_simple periodic 5` + * or with MPI: + * > `mpirun -np 4 p4est_simple periodic 5` + * + * * No. of trees: 1 + * * Maximum refinement level: chosen on the command line as 5 + * + * \image html periodic_balanced_lv5.png + * + * * Example: circle + * + * Create a connectivity structure for an donut-like circle. + * The circle consists of 6 trees connecting each other by their faces. + * The trees are laid out as a hexagon between \f$[-2, 2]\f$ in the y direction + * and \f$[-\sqrt{3}, \sqrt{3}]\f$ in the x direction. The hexagon has flat + * sides along the y direction and pointy ends in x. + * + * Usage: + * > `p4est_simple circle 5` + * or with MPI: + * > `mpirun -np 4 p4est_simple circle 5` + * + * * No. of trees: 6 + * * Maximum refinement level: chosen on the command line as 5 + * + * \image html circle_balanced_lv5.png + * + * * Example: drop + * + * Create a connectivity structure for a five-trees geometry with a hole. + * The geometry covers the square \f$[0, 3]^2\f$, where the hole is \f$[1, 2]^2\f$. + * + * Usage: + * > `p4est_simple drop 5` + * or with MPI: + * > `mpirun -np 7 p4est_simple drop 5` + * + * * No. of trees: 5 + * * Maximum refinement level: chosen on the command line as 5 + * \image html drop_balanced_lv5.png + * + * * Example: moebius + * + * Create a connectivity structure for a five-tree moebius band. + * + * Usage: + * > `p4est_simple moebius 5` + * or with MPI: + * > `mpirun -np 4 p4est_simple moebius 5` + * + * * No. of trees: 5 + * * Maximum refinement level: chosen on the command line as 5 + * + * \image html moebius_balanced_lv5.png + */ + + /** \page Examples2 Documentation for selected 3D example programs + * + * The p4est library comes with various example programs. + * They are kept under the subdirectory + * [example](https://github.com/cburstedde/p4est/tree/master/example). + * Most have both a 2D and a 3D version. + * When the library is configured `--enable-mpi`, they can all be run in + * parallel on any number of MPI ranks, even on small computers. + * + * Before proceeding with the examples on this page, it is highly + * recommended to get familiar with the programs, starting from 2D + * examples in \ref Examples. + * + * One first helpful program to try out is called `p4est_simple` (2D version) + * and `p8est_simple` (3D version), both under + * [simple](https://github.com/cburstedde/p4est/tree/master/example/simple). + * On this page, we showcase some results of 3D example programs further + * below on this page, and we encourage everyone to play with the command + * line arguments. + * + * ### The historic simple example + * + * The example can be found in \ref simple/simple3.c. It is a 3D version of + * \ref simple/simple2.c + * The refinement pattern is generated by some hardcoded prescriptions based + * on a octants's tree number, refinement level and coordinates. + * Please see the documentation under the link for a full list of configurations. + * + * This program creates/refines & coarsens/balances/partitions one + * of several available geometries specified on the command line. + * As a result, the output VTK files document all + * the steps of the mesh manipulation process. + * + * * Example: unit + * + * Create a connectivity structure for a stand-alone unit cube. + * + * Usage: + * > `p8est_simple unit 5` + * or with MPI: + * > `mpirun -np 4 p8est_simple unit 5` + * + * * No. of trees: 1 + * * Maximum refinement level: chosen on the command line as 5 + * + * \image html unit_balanced_lv5.png + * + * * Example: periodic + * + * Further enriching the upper example, this example program creates a + * connectivity structure of a unit cube with all-periodic boundary conditions. + * + * Usage: + * > `p8est_simple periodic 5` + * or with MPI: + * > `mpirun -np 4 p8est_simple periodic 5` + * + * * No. of trees: 1 + * * Maximum refinement level: chosen on the command line as 5 + * + * \image html periodic_3d_balanced_lv5.png + * + * * Example: two wraps + * + * Further developing the ideas above, this example program creates a + * connectivity structure of two wrap-up cubes (each of which is a tree). The + * visually not connected far ends of the two cubes are periodically identical. + * + * Usage: + * > `p8est_simple twowraps 5` + * or with MPI: + * > `mpirun -np 7 p8est_simple twowraps 5` + * + * * No. of trees: 2 + * * Maximum refinement level: chosen on the command line as 5 + * \image html twowraps_balanced_lv5.png + * + */ + +/** \example steps/p4est_step1.c + * This software refines a basic domain using given image data. + * As a result, the resulting VTK file showcases the message 'Hello + * World' through the mesh. + * + * Usage: + * > `p4est_step1` + */ + +/** \example simple/simple2.c + * This application generates, refines, and adjusts a mesh set on the command line. + * The resulting VTK files visually present each stage of the mesh + * modification procedure. + * + * Usage: + * > `p4est_simple ` + * possible configurations: + * * unit Refinement on the unit square. + * * brick Refinement on a regular forest of octrees. + * * three Refinement on a forest with three trees. + * * evil Check second round of refinement with np=5 level=7 + * * evil3 Check second round of refinement on three trees + * * pillow Refinement on a 2-tree pillow-shaped domain. + * * moebius Refinement on a 5-tree Moebius band. + * * star Refinement on a 6-tree star shaped domain. + * * cubed Refinement on a 6-tree cubed sphere surface. + * * disk Refinement on a 5-tree spherical standard disk. + * * xdisk Refinement on a 5-tree spherical disk periodic in x. + * * ydisk Refinement on a 5-tree spherical disk periodic in y. + * * pdisk Refinement on a 5-tree spherical disk, periodic b.c. + * * periodic Refinement on the unit square with all-periodic b.c. + * * rotwrap Refinement on the unit square with weird periodic b.c. + * * circle Refinement on a 6-tree donut-like circle. + * * drop Refinement on a 5-trees geometry with an inner hole. + * * icosahedron Refinement on the sphere + * * shell2d Refinement on a 2d shell with geometry. + * * disk2d Refinement on a 2d disk with geometry. + * * bowtie Refinement on a 2-tree bowtie domain. + */ + +/** \example simple/simple3.c + * This application generates, refines, and adjusts a mesh set on the command line. + * The resulting VTK files visually present each stage of the mesh + * modification procedure. + * + * Usage: + * > `p8est_simple ` + * possible configurations: + * * unit The unit cube. + * * brick The brick connectivity. + * * periodic The unit cube with all-periodic boundary conditions. + * * rotwrap The unit cube with various self-periodic b.c. + * * twocubes Two connected cubes. + * * twowrap Two cubes with periodically identified far ends. + * * rotcubes A collection of six connected rotated cubes. + * * shell A 24-tree discretization of a hollow sphere. + * * sphere A 13-tree discretization of a solid sphere. + */