Add planar meshes to framework/mesh

docs/developers_guide/framework/mesh.md

@@ -75,3 +75,62 @@ vtk_dir = base_mesh_vtk
 # whether to extract the vtk output in lat/lon space, rather than on the sphere
 vtk_lat_lon = False
 ```
+
+(dev-planar-meshes)=
+
+## Planar Meshes
+
+So far, there is not support for creating planar meshes in the polaris
+framework.  But there are helpful functions for creating both 
+[uniform hexagonal meshes](http://mpas-dev.github.io/MPAS-Tools/stable/mesh_creation.html#uniform-planar-meshes)
+and [more general planar meshes](http://mpas-dev.github.io/MPAS-Tools/stable/mesh_creation.html#planar-meshes)
+using the [mpas_tools](http://mpas-dev.github.io/MPAS-Tools/stable/index.html)
+package.
+
+### Uniform planar meshes
+
+You can build a uniform planar mesh in a step by calling
+{py:func}`mpas_tools.planar_hex.make_planar_hex_mesh()`.  The mesh is defined
+by the number of cells in the x and y directions (`nx` and `ny`), the 
+resolution `dc` in km (`dc` is the distance between adjacent cell centers),
+and some (admittedly oddly named) parameters for determining which directions
+(if any) are periodic, `nonperiodic_x` and `nonperiodic_y`.
+
+There are a few considerations for determining `nx` and `ny`.  Typically,
+we need at least 4 grid cells in each direction for MPAS-Ocean to be well
+behaved, and similar restrictions may apply to other components.  Second,
+`ny` needs to be an even number because of the staggering of the hexagons used
+to create the mesh.  (We typically also use even numbers for `nx` but that is
+not strictly necessary.)
+
+Another important consideration is that the physical size of the mesh in the x
+direction is `lx = nx * dc`.  However, the physical extent in the y direction 
+is `ly = (np.sqrt(3) / 2) * ny * dc` because of the staggering of the hexagons
+in that direction.  As a result, you if you know the desired domain size `ly`, 
+you need to compute the number of cells in that direction including an extra
+factor of `2. / np.sqrt(3)`, as in this example:
+```python
+import numpy as np
+from mpas_tools.planar_hex import make_planar_hex_mesh
+
+lx = 500e3
+ly = 160e3
+dc = 1e3
+
+nx = max(2 * int(0.5 * lx / dc + 0.5), 4)
+# factor of 2/sqrt(3) because of hexagonal mesh
+ny = max(2 * int(0.5 * ly * (2. / np.sqrt(3)) / dc + 0.5), 4)
+
+ds_mesh = make_planar_hex_mesh(nx=nx, ny=ny, dc=dc, nonperiodic_x=False,
+                               nonperiodic_y=True)
+```
+
+### General planar meshes
+
+One way to create a more general planar mesh is by calling
+{py:func}`mpas_tools.mesh.creation.build_mesh.build_planar_mesh()`, which uses 
+JIGSAW to build a mesh with variable resolution.  See
+[Planar Meshes](http://mpas-dev.github.io/MPAS-Tools/stable/mesh_creation.html#planar-meshes)
+for more details.  We plan to create framework-level steps for planar meshes 
+similar to {py:class}`polaris.mesh.QuasiUniformSphericalMeshStep` and
+{py:class}`polaris.mesh.IcosahedralMeshStep` in the not too distant future.