Reorganize the framework and organization in the developer's guide #38
Conversation
|
@xylar Thanks for catching that and adding those images |
|
@cbegeman, I think it makes sense to do a similar reorganization of "Organization", which is ridiculously long as well. But I'll wait to see what you think before I do that as well. And I'll probably do it in another PR to keep each PR from becoming overwhelming. This would be an opportunity to add something about planar meshes related to #37. And there's also some confusion about |
|
...and I changed my mind again after playing around with reorganizing a bit. It doesn't feel like details about running E3SM components or meshes belong in "Organization" so let's stick with "Framework". |
|
Back to draft mode so I can include some more reorganization, including info on planar meshes. |
xylar
force-pushed
the
reorg-dev-framework
branch
from
18c135f to
5975338
Compare
| (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. |
There was a problem hiding this comment.
@cbegeman, this section is new. Please give it a look and let me know if it addresses #37 (review). Feel free to suggest changes.
xylar
changed the title
|
Thanks @cbegeman! |
This merge organizes the framework and organization documentation in the developer's guide into individual pages for better readability, easier organization, and to facilitate future contributions.
I have also fixed an issue where the example documentation for how to add new test groups to the API wasn't rendering correctly and was getting added to the list of auto-generated docstrings. It is now rendering as example code (as it should) and not autogenerating any documentation based on docstring.
I also added 2 images missing from #33.
I added a section on planar meshes (including considerations for the number of cells in the y direction because of the staggering of hexagons) to the framework/mesh page.
Checklist
api.md) has any new or modified class, method and/or functions listed