Fix description of the gridded bathymetry data format in docs (#134)

* fix description of the gridded bathymetry data format

* Modify Docs about 2D topography sizing

Made a note in the section on refinement regions that automatic sizing can be done with a topography included and created a link. Modified the sizing discussion in the 3D meshing section to say that it can be sued to size 2D meshes.

* Add tl;dr

Added a section to the beginning of the index and the introduction that outlines what can be done with HOHQMesh. [These are the same. Should find out how to "include" a file in markdown to have just one copy]

* Update introduction.md

Fix a typo

* Update README.md

Add the tl;dr to the front page, too.

* Update README.md

Fix links

* Update the-model.md

Fix a formatting error

* Update introduction.md

Fix file names.

* Restructure model definition

Move and add model blocks used in the 3D meshing to the description of the model.

* More doc edits

Make changes sugersted by Andrew, plus a few more, including formatting changes.

---------

Co-authored-by: David Kopriva <[email protected]>
Co-authored-by: DavidAKopriva <[email protected]>

Author: andrewwinters5000

Documentation/docs/introduction.md

@@ -1,3 +1,30 @@
+
+# TL;DR. What you can do with HOHQMesh<a name="WhatToDo"></a>
+
+To use HOHQMesh to generate all-quadrilateral meshes with arbitrary order boundary elements you use a [control file](the-controlfile.md) to
+
+- Define a [`MODEL`](the-model.md#TheModel) consisting of
+	- An optional closed outer [boundary curve](the-model.md#Boundaries) made up of one or a chain of curved segments defined by primitives like straight [line segments](the-model.md#EndPointsLine), [circular arcs](the-model.md#CircularArc), [elliptic arcs](the-model.md#ParametricEqn), [splines](the-model.md#Spline), or [equations](the-model.md#ParametricEqn)
+	- Zero or more closed inner boundary curves defined in the same way
+	- Zero or more internal boundary curves that define boundaries for multiple material applications
+	- An optional bottom [topography](three-dimensional-hexahedral-meshes.md#Topography) defined either in functional form or from a file to use to [refine](three-dimensional-hexahedral-meshes.md#SizingTopography) a 2D mesh around bottom features. (For example for shallow water equation computations.)
+
+- Tell it how to mesh the model with a [`CONTROL_INPUT`](the-control-input.md) section to control the meshing process by
+  - Setting [run parameters](the-control-input.md#RunParameters) that specify where to write the results, specify the mesh and plot file formats and the polynomial order of the boundary curves
+  - Setting a [background grid](the-control-input.md#BackgroundGrid) size to specify the largest element size desired
+  - Setting how the mesh should be [smoothed](the-control-input.md#Smoother)
+  - Defining optional [refinement regions](the-control-input.md#RefinementRegions) to allow manual refinement of the mesh to emphasize specific regions not indicated by the boundary curves or topography.
+
+HOHQMesh will automatically generate a mesh with curved elements sized according to the geometry, like the curvature of the boundary curves and bottom topography, and the distance between boundary curves. It will generate a mesh that is symmetric about a symmetry line if segments of the outer boundary are defined as [symmetry boundaries](the-model.md#Symmetry).
+
+Additionally, you can generate an all [hexahedral](three-dimensional-hexahedral-meshes) mesh by extruding a quadrilateral mesh by
+
+- [Simple extrusion](three-dimensional-hexahedral-meshes.md#Extrusion) along a coordinate direction
+- [Simple rotation](three-dimensional-hexahedral-meshes.md#Rotation) about an axis
+- [Sweeping](three-dimensional-hexahedral-meshes.md#Sweeping) a quadrilateral mesh along a curve and optionally [scaling](three-dimensional-hexahedral-meshes.md#Scaling) the width along the way
+
+One can have the bottom of a hexahedral mesh follow a prescribed [topography](three-dimensional-hexahedral-meshes.md#Topography) defined in functional form or from data. A 3D mesh can also be [sized](three-dimensional-hexahedral-meshes.md#SizingTopography) according to the curvature of the bottom topography.
+
 # Introduction
 
 Multidomain spectral methods, of which spectral element methods (SEMs) are a subclass, were introduced by Patera  (for elliptic and parabolic equations) and by Kopriva (for hyperbolic systems) to increase the efficiency of spectral methods and to apply them to complex geometries. Although somewhat controversial at the time -- questions were raised whether it was wise to not use the highest order polynomial possible  for a given number of degrees of freedom -- the methods have become so commonly used within the community that the updated book by Canuto et al.  is subtitled  “Fundamentals in Single Domains.”

Documentation/docs/the-control-input.md

@@ -73,6 +73,8 @@ Just leave out any of the optional parameters if you want the default values to
 ![Refinements](https://user-images.githubusercontent.com/3637659/121807868-46ae1680-cc56-11eb-8941-c9ad8d259da2.png)
 <p align = "center"> Fig. 19. Two refinement centers and a refinement line</p>
 
+Mesh sizing is done automatically according to the curvature of boundary curves and the curvature of a bottom topography that can be supplied. See the section on [topography](the-model.md#SizingTopography) for more information on the latter.
+
 Manual scaling of the mesh size can be performed by including any combination of
 
 * Refinement Centers
@@ -127,7 +129,7 @@ Refinement regions are defined within a `REFINEMENT_REGIONS` block, e.g.
 
 The ordering of the blocks within the `REFINEMENT_REGIONS` block is arbitrary.
 
-### Base Material Definition<a name="BaseMaterialDefinition"></a>
+## Base Material Definition<a name="BaseMaterialDefinition"></a>
 
 If the ISM-MM mesh file format is requested to produce multiple material meshes, the material name for a given region is given by the name of the curve bounding it, except for the outermost region. For the outermost region it is necessary to set the background material name in a `MATERIALS` block, e.g.
 

Documentation/docs/the-model.md

@@ -4,6 +4,9 @@ At the present time, HOHQMesh is designed to generate quadrilateral meshes in ge
 ![Meshables](https://user-images.githubusercontent.com/3637659/121807852-3302b000-cc56-11eb-93a9-e9c2e1b4ede8.png)
 <p align = "center"> Fig. 15. Meshable regions</p>
 
+## Boundaries<a name="Boundaries"></a>
+
+
 The two dimensional domain to be meshed can be bounded by at most one exterior boundary curve (which can be composed of a chain of curves), as in 15(a) and 15(b), above, and any number of interior boundary curves that either create holes or interfaces along which element edges are forced to lie. For purely external problems, a rectangular outer boundary can be implicitly included, as shown in 15(c).
 
 If no model block is included at all, then a purely Cartesian mesh will be created using parameters set in the control file.
@@ -13,11 +16,15 @@ As an example, the model in Fig. 16 has one outer boundary - the outer triangle
 ![AllFeatures](https://github.com/user-attachments/assets/2f12ca1c-8a20-4c7d-98e6-9d619562a34d)
 <p align = "center"> Fig. 16. A mesh whose model uses all curve types. Three `END_POINTS_LINE`s for the outer triangle. A `SPLINE_CURVE` for the free-form inner boundary, circles defined by a `PARAMETRIC_EQUATION_CURVE` and by a `CIRCULAR_ARC` curve, and an ellipse defined by an `ELLIPTIC_ARC` curve. (<em>Examples/2D/AllFeatures</em>).</p>
 
+### Internal Boundaries<a name="Interfaces"></a>
+
  It is also possible to include interface boundaries whose interiors are also meshed. This allows one to force element boundaries along curves and to assign different material properties to each region bounded by them. The property is named by the innermost boundary in which an element lies. An example of a domain with two interface boundaries is shown in Fig. 17. **Right now, interface curves must be defined in the model definition from outer to inner to properly assign material names**. Thus, the innermost circle in Fig. 17 is defined after its enclosing circle. This restriction can be removed by adding code to test whether a given curve lies within another.
 
 ![B&M](https://user-images.githubusercontent.com/25242486/241190479-ba50d797-3bd9-41b1-bc38-03fc86f8c3da.png)
 <p align = "center"> Fig. 17. Mesh with interior interfaces bounded by circles.</p>
 
+### Symmetric Meshes<a name="Symmetry"></a>
+
 The mesh generator generates unstructured meshes, and there is no reason in general why a mesh must be symmetric if the model is symmetric. Since symmetry can be a desirable feature, HOHQMesh allows one to define a symmetry boundary about which the mesh will be symmetric by setting boundary names as ":symmetry" (with a colon, so as not to interfere with some other use of the name). The symmetry boundary must be a straight line (no matter how that is defined, see below) and multiple symmetry boundaries must be co-linear. What HOHQMesh does is take a model and mesh it. Then, if one or more of the outer boundary curves are named ":symmetry", that mesh will be reflected about the symmetry line and the result will be a perfectly symmetric mesh, to within rounding error. An example is shown in Fig. 18. If the curve designated as ":symmetry" is not straight, or if any of multiple lines so designated are not co-linear, then an error is posted and the mesh will not be reflected.
 
 ![NotREFL](https://github.com/trixi-framework/HOHQMesh/assets/25242486/5e145806-1acb-43c4-b712-ea6eeb703c64)
@@ -188,6 +195,79 @@ block. Any number of curves can be chained together. The chain itself is also gi
 
 Again, the indentation is for readability only, as is the line spacing between the blocks. (Blank lines and lines starting with “%” are ignored.) Also remember that the chain is defined counter-clockwise, and the curves within the chain must be ordered and oriented properly. Chains cannot be chained together. Rem: The use of `PARAMETRIC_EQUATION_CURVE`s in this example predates the addition of the `END_POINTS_LINE` curves, which would be simpler to use here.
 
+## Bottom Topography
+
+A bottom topography can also be added to the model. The most obvious use is when generating three dimensional meshes, where the bottom follows a given profile. But topography can also be used to size the mesh, which is useful for the solution of two-dimensional shallow water flows.
+
+A bottom topography can be defined in one of two ways:
+
+* By supplying a functional form, f(x,y)
+* By supplying gridded data in a file
+
+### Topography from a Functional Form
+The simplest way to define the bottom topography is with an equation in a `TOPOGRAPHY` block, e.g.,
+
+        \begin{TOPOGRAPHY}
+           eqn = h(x,y) = x^2 + y^2
+           sizing = ON \or\ OFF (Optional)
+        \end{TOPOGRAPHY}
+
+The height function takes two arguments, which are the physical x-y coordinates, unlike the parametric coordinates that define boundary curves. The `sizing` key is optional, with the default being `OFF`.
+
+### Topography from Data
+
+Alternatively, the bottom topography data can be read in from a file, e.g.,
+
+        \begin{TOPOGRAPHY}
+           data file = path/to/bottom_data.txt
+           sizing = ON \or\ OFF (Optional)
+        \end{TOPOGRAPHY}
+        
+ The `sizing` key is optional, with the default being `OFF`.
+ 
+From this data, a bicubic interpolation is used to compute the bottom topography information.
+Currently this strategy of bottom topography extrusion relies on *gridded data*. The data file is assumed to come as separate lists of the x coordinate points, with length $n$, the
+y coordinate points, with length $m$, and the z coordinate points where the grid data is ordered slice-by-slice in the y direction, with size $m \times n$. Below a small example is provided to clarify the
+data file format
+
+     ! Header with the number of points in the x and y direction
+      75 50
+     ! x node values
+     x1
+     ...
+     x75
+     ! y node values
+     y1
+     ...
+     y50
+     ! z node values
+     z1,1
+     z2,1
+     ...
+     z50,1
+     z1,2
+     ...
+     z50,2
+     ...
+     z1,75
+     ...
+     z50,75
+
+### Sizing the Mesh with Bottom Topography<a name="SizingTopography"></a>
+
+When
+
+		sizing = ON
+
+in a TOPOGRAPHY block, e.g.
+
+        \begin{TOPOGRAPHY}
+           eqn    = h(x,y) = x^2 + y^2
+           sizing = ON
+        \end{TOPOGRAPHY}
+
+a two-dimensional mesh is sized according to the curvature of the topography, but does not change the z values of the mesh. For an example, see the top portion of [Fig. 26](three-dimensional-hexahedral-meshes.md#SizingTopography).
+
 ## The Model Definition<a name="TheModel"></a>
 The model (there is at most one) defines the region that is to be meshed. It is marked by
 
@@ -221,7 +301,27 @@ Interior interface boundary curves are defined inside the `INTERFACE_BOUNDARIES`
 
 Interface boundaries, unlike interior boundaries, do not create holes in model domain or the mesh. _Interface boundaries that are contained (embedded) in other interface boundaries must be defined within the block in order from outer to inner to properly define the material names_. The ordering of interface boundaries that are not embedded in another is not important. (Additions to HOHQMesh to remove this restriction will require code to determine whether or not a given curve is embedded within another, and has not yet been implemented. HOHQMesh essentially uses a painters algorithm to specify the material names.) If interface curves are not being used to delineate material boundaries (i.e. for mesh alignment alone and not with the ISM-MM mesh file format), then the ordering is unimportant.
 
-###Example
+Bottom topography, if any, is defined in the `MODEL` inside a `TOPOGRAPHY` block, for either 2D (for sizing purposes) or 3D (to vary the bottom elevation) meshes,
+
+	\begin{TOPOGRAPHY}
+	...
+	\end{TOPOGRAPHY}
+
+Two types of blocks are relevant only to three-dimensional meshes. They are the
+
+	\begin{SWEEP_CURVE}
+		...
+	\end{SWEEP_CURVE}
+
+which defines the curve along which a 3D sweep is made. The second is  a scale factor
+
+	\begin{SWEEP_SCALE_FACTOR}
+		...
+	\end{SWEEP_SCALE_FACTOR}
+
+which allows the size of the mesh to vary along a sweep curve. Details on what these blocks do can be found in the [3D Meshing](three-dimensional-hexahedral-meshes.md) section.
+
+### Example
 
 As an example, the following defines a model that has a single circular outer boundary and three inner circular boundaries. Two of the curves are defined within a CHAIN (even though there is only a single curve within each). One of them is standalone. Note that *between* the blocks, comments can be inserted starting with “%”. As usual, indentation is for the reader’s eyes only.
 Rem: This example also predates the addition of the `CIRCULAR_ARC` curve definition, which could be used to define the circles instead.

Documentation/docs/three-dimensional-hexahedral-meshes.md

@@ -1,5 +1,5 @@
 # Three Dimensional Hexahedral Meshes
-HOHQMesh can also generate 3D hexahedral meshes by extruding or sweeping a two dimensional mesh. Topography can also be added to the bottom of the domain either through a functional form or from data supplied through a file. Finally, when bottom topography is present, the mesh along the bottom can be sized according to the bottom curvature.
+HOHQMesh can also generate 3D hexahedral meshes by extruding or sweeping a two dimensional mesh. Topography can also be added to the bottom of the domain either through a functional form or from data supplied through a file. Finally, when bottom topography is present, the mesh along the bottom can be sized according to the bottom curvature for either 2D or 3D meshes.
 
 To tell the mesher that you want a hex mesh, you add an algorithm block to the `CONTROL_INPUT` block for how the 3D extrusion will be done. Currently there are three:
 
@@ -101,52 +101,12 @@ The equation for the scaling is scalar `PARAMETRIC_EQUATION` (as opposed to a `P
 ![Pond](https://user-images.githubusercontent.com/3637659/121807861-40b83580-cc56-11eb-8d97-388924e08dee.png)
 <p align = "center"> Fig. 24. Simple Extrusion of a semi-circular mesh with bottom topography</p>
 
-When using the `SIMPLE_EXTRUSION` algorithm, bottom topography can be defined in one of two ways:
+The bottom of a three dimensional mesh can vary in height according to a bottom topography. One defines the topography in the [`MODEL`](the-model.md) block in one of two ways:
 
 * By supplying a functional form, f(x,y)
 * By supplying gridded data in a file
 
-### Topography from a Functional Form
-The simplest way to define the bottom topography is with an equation in a `TOPOGRAPHY` block, e.g.,
-
-        \begin{TOPOGRAPHY}
-           eqn = h(x,y) = x^2 + y^2
-        \end{TOPOGRAPHY}
-
-The height function takes two arguments, which are the physical x-y coordinates, unlike the parametric coordinates that define boundary curves. Fig. 24 above shows an example of such a bottom topography.
-
-### Topography from Data
-Alternatively, the bottom topography data can be read in from a file, e.g.,
-
-        \begin{TOPOGRAPHY}
-           data file = path/to/bottom_data.txt
-        \end{TOPOGRAPHY}
-
-From this data a bicubic interpolation is used to compute the bottom topography information.
-Currently this strategy of bottom topography extrusion relies on gridded data. The data file is assumed to come as separate lists of the x coordinate points, the
-y coordinate points, and the z coordinate points where the grid data is ordered slice-by-slice in the y direction. Below a small example is provided to clarify the
-data file format
-
-     ! Header with the number of points in the x and y direction
-      75 50
-     ! x node values
-     x1
-     ...
-     x75
-     ! y node values
-     y1
-     ...
-     y50
-     ! z node values
-     z1,1
-     z2,1
-     ...
-     z75,1
-     z1,2
-     ...
-     z75,2
-     ...
-     z75,50
+See the [`MODEL`](the-model.md) section for details. Fig. 24 above shows an example of a bottom topography set with a bottom function, while Figs. 25 and 26 use data to describe Mt. St. Helens. 
 
 ![MtStHelens](https://user-images.githubusercontent.com/25242486/157440694-b8f1d9d5-adbf-4f5b-9de0-f89f675c584f.png)
 <p align = "center"> Fig. 25. Simple Extrusion of a rectangular mesh with a mountain bottom topography read in from a file</p>
@@ -155,17 +115,15 @@ data file format
 ![SeaMountWithSizing](https://user-images.githubusercontent.com/85404032/160676054-d5f12eee-4f2b-4674-8861-1d131e9e8493.png)
 <p align = "center"> Fig. 26. Simple Extrusion of a semi-circular mesh with a bottom topography and local refinement depending on its curvature</p>
 
-Finally, the grid can be sized along the bottom by adding the command
+When
 
 		sizing = ON
 
-to any TOPOGRAPHY block, e.g
+in a TOPOGRAPHY block, e.g.
 
-		\begin{TOPOGRAPHY}
-		   data file = path/to/bottom_data.txt
-		   sizing    = ON
-		\end{TOPOGRAPHY}
-
-It can also be turned `OFF', or the line deleted, to not size the bottom.
+        \begin{TOPOGRAPHY}
+           eqn    = h(x,y) = x^2 + y^2
+           sizing = ON
+        \end{TOPOGRAPHY}
 
-The sizer will then size the grid along the bottom according to the curvature of the topography. An example is shown in Fig. 26.
+the sizer will size the grid along the bottom according to the curvature of the topography for a 3D mesh. An example is shown in Fig. 26. If only a two dimensional mesh is requested, then it is sized according to the curvature, but the z-values of the 2D mesh are not changed, the result looking like the top of Fig. 26.