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 and more general planar meshes using the mpas_tools package.

Uniform planar meshes

You can build a uniform planar mesh in a step by calling 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 polaris.mesh.planar.compute_planar_hex_nx_ny() to take care of this for you:

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:

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 mpas_tools.mesh.creation.build_mesh.build_planar_mesh(), which uses JIGSAW to build a mesh with variable resolution. See Planar Meshes for more details. We plan to create framework-level steps for planar meshes similar to polaris.mesh.QuasiUniformSphericalMeshStep and polaris.mesh.IcosahedralMeshStep in the not too distant future.