Merge pull request #305 from xylar/add-mesh-component

Add a `mesh` component

Author: xylar

docs/conf.py

@@ -48,7 +48,7 @@
 ]
 
 autosummary_generate = ['developers_guide/api.md',
-                        # 'developers_guide/landice/api.md',
+                        'developers_guide/mesh/api.md',
                         'developers_guide/ocean/api.md',
                         'developers_guide/seaice/api.md']
 

docs/developers_guide/api.md

@@ -12,6 +12,7 @@ documentation.
 :maxdepth: 1
 :titlesonly: true
 
+mesh/api
 ocean/api
 seaice/api
 ```
@@ -187,18 +188,6 @@ seaice/api
    ModelStep.partition
 ```
 
-### components
-
-```{eval-rst}
-.. currentmodule:: polaris.tasks
-
-.. autosummary::
-   :toctree: generated/
-
-   get_components
-```
-
-
 ### config
 
 ```{eval-rst}
@@ -277,6 +266,17 @@ seaice/api
    IcosahedralMeshStep.get_cell_width
 ```
 
+### Uniform Spherical Base Mesh Step
+
+```{eval-rst}
+.. currentmodule:: polaris.mesh.add_step
+
+.. autosummary::
+   :toctree: generated/
+
+   add_uniform_spherical_base_mesh_step
+```
+
 ### model_step
 
 ```{eval-rst}
@@ -353,6 +353,16 @@ seaice/api
    MappingFileStep.run
 ```
 
+### resolution
+
+```{eval-rst}
+.. currentmodule:: polaris.resolution
+
+.. autosummary::
+   :toctree: generated/
+
+   resolution_to_string
+```
 
 ### streams
 

docs/developers_guide/framework/config.md

@@ -101,15 +101,15 @@ resolution's work directory:
 
 ```python
 from polaris.config import PolarisConfigParser
-from polaris.ocean.resolution import resolution_to_subdir
+from polaris.resolution import resolution_to_string
 from polaris.tasks.ocean.baroclinic_channel.default import Default
 from polaris.tasks.ocean.baroclinic_channel.init import Init
 from polaris.tasks.ocean.baroclinic_channel.rpe import Rpe
 
 
 def add_baroclinic_channel_tasks(component):
     for resolution in [10., 4., 1.]:
-        resdir = resolution_to_subdir(resolution)
+        resdir = resolution_to_string(resolution)
         resdir = f'planar/baroclinic_channel/{resdir}'
 
         config_filename = 'baroclinic_channel.cfg'

docs/developers_guide/framework/index.md

@@ -2,23 +2,28 @@
 
 # Framework
 
-All of the {ref}`dev-packages` that are not in the two components (`ocean`
+All of the {ref}`dev-packages` that are not in the components (`mesh`, `ocean`
 and `seaice`) belong to the polaris framework.  Some of these
 modules and packages are used by the {ref}`dev-command-line`, while others are
 meant to be called within tasks and steps to simplify tasks like adding
 input and output files, downloading data sets, building up config files,
-yaml files, namelists and streams files, setting up and running the E3SM 
-component, and  verifying the output by comparing steps with one another or 
+yaml files, namelists and streams files, setting up and running the E3SM
+component, and  verifying the output by comparing steps with one another or
 against a baseline.
 
+The framework is organized to separate tasks and shared framework code. Tasks
+for each component are located in `polaris.tasks.<component>`, while shared
+framework code (e.g., config files, YAML files, utilities) is located in
+`polaris.<component>`. This separation ensures clarity and avoids circular
+dependencies.
+
 ```{toctree}
 :titlesonly: true
 
 commands
 config
 logging
 io
-mesh
 mpas
 model
 provenance

docs/developers_guide/mesh/api.md

@@ -0,0 +1,25 @@
+# mesh
+
+```{eval-rst}
+.. currentmodule:: polaris.tasks.mesh.add_tasks
+
+.. autosummary::
+   :toctree: generated/
+
+   add_mesh_tasks
+```
+
+## Tasks
+
+### Base Mesh Tasks
+
+```{eval-rst}
+.. currentmodule:: polaris.tasks.mesh.base
+
+.. autosummary::
+   :toctree: generated/
+
+   add_base_mesh_tasks
+
+   BaseMeshTask
+```

docs/developers_guide/framework/mesh.md renamed to docs/developers_guide/mesh/framework.md

@@ -1,6 +1,6 @@
-(dev-mesh)=
+(dev-mesh-framework)=
 
-# Mesh
+# Mesh Framework
 
 (dev-spherical-meshes)=
 
@@ -81,7 +81,7 @@ vtk_lat_lon = False
 ## Planar Meshes
 
 So far, there is not support for creating planar meshes in the polaris
-framework.  But there are helpful functions for creating both 
+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)
@@ -91,12 +91,12 @@ package.
 
 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 
+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 
+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:
 
@@ -108,16 +108,16 @@ 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 
+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 
+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`, 
+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
@@ -139,9 +139,9 @@ ds_mesh = make_planar_hex_mesh(nx=nx, ny=ny, dc=dc, nonperiodic_x=False,
 ### 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 
+{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 
+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.

docs/developers_guide/mesh/index.md

@@ -0,0 +1,14 @@
+(dev-mesh)=
+
+# Mesh component
+
+The `mesh` component defines tasks and steps related to generating and
+manipulating MPAS meshes.  There are currently no component-level config
+options.
+
+```{toctree}
+:titlesonly: true
+
+tasks/index
+framework
+```

docs/developers_guide/mesh/tasks/base.md

@@ -0,0 +1,10 @@
+(dev-mesh-base)=
+
+# Base Mesh Task
+
+The the base mesh tasks defined by {py:class}`polaris.tasks.mesh.base.BaseMeshTask`
+can be used to generate quasi-uniform (`qu`) and subdivided icosahedral
+(`icos`) spherical meshes at quasi-uniform resolutions ranging from 30 to 480
+km.  These "base" meshes cover the full sphere (include both continents and
+ocean regions).
+

docs/developers_guide/mesh/tasks/index.md

@@ -0,0 +1,9 @@
+(dev-mesh-tasks)=
+
+# Tasks
+
+```{toctree}
+:titlesonly: true
+
+base
+```

docs/developers_guide/ocean/api.md

@@ -7,6 +7,8 @@
    :toctree: generated/
 
    Ocean
+
+   add_tasks.add_ocean_tasks
 ```
 
 ## Tasks
@@ -394,16 +396,6 @@
    get_time_interval_string
 ```
 
-### Spherical Base Mesh Step
-
-```{eval-rst}
-.. currentmodule:: polaris.ocean.mesh.spherical
-
-.. autosummary::
-   :toctree: generated/
-
-   add_spherical_base_mesh_step
-```
 
 ### Reference Potential Energy (RPE)