Merge pull request #359 from xylar/add-so-rrs-meshes

Add SO and RRS meshes

Author: xylar

docs/developers_guide/api.md

@@ -268,16 +268,20 @@ seaice/api
    IcosahedralMeshStep.get_cell_width
 ```
 
-### Uniform Spherical Base Mesh Step
+### Spherical Base Meshes
 
 ```{eval-rst}
 .. currentmodule:: polaris.mesh.base
 
 .. autosummary::
    :toctree: generated/
 
-   add_uniform_spherical_base_mesh_step
+   add_spherical_base_mesh_step
    get_base_mesh_steps
+   rrs.RRSBaseMesh
+   rrs.RRSBaseMesh.build_cell_width_lat_lon
+   so.SOBaseMesh
+   so.SOBaseMesh.build_cell_width_lat_lon
 ```
 
 ### model_step
@@ -371,6 +375,7 @@ seaice/api
    :toctree: generated/
 
    resolution_to_string
+   resolution_to_string_and_units
 ```
 
 ### streams

docs/developers_guide/mesh/framework.md

@@ -0,0 +1,13 @@
+(dev-mesh-framework)=
+
+# Mesh Framework
+
+The framework for the `mesh` component provides classes and functions for
+creating spherical and planar mesh steps.
+
+```{toctree}
+:titlesonly: true
+
+spherical
+planar
+```

docs/developers_guide/mesh/framework/images/rrs.png

@@ -0,0 +1,69 @@
+(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](https://mpas-dev.github.io/MPAS-Tools/stable/mesh_creation.html#uniform-planar-meshes)
+and [more general planar meshes](https://mpas-dev.github.io/MPAS-Tools/stable/mesh_creation.html#planar-meshes)
+using the [mpas_tools](https://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`. There is a
+framework level function {py:func}`polaris.mesh.planar.compute_planar_hex_nx_ny()`
+to take care of this for you:
+
+```python
+from polaris.mesh.planar import compute_planar_hex_nx_ny
+
+
+nx, ny = compute_planar_hex_nx_ny(lx, ly, resolution)
+```
+
+What follows is an explanation of the subtleties that are accounted for in that
+function. 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, 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](https://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.