Update Developer's Guide with these changes

docs/developers_guide/ocean/api.rst

@@ -166,32 +166,25 @@ test cases and steps
    mesh.Mesh
    mesh.Mesh.configure
    mesh.Mesh.run
-   mesh.cull.cull_mesh
-   mesh.mesh.MeshStep
-   mesh.mesh.MeshStep.setup
-   mesh.mesh.MeshStep.run
-   mesh.mesh.MeshStep.build_cell_width_lat_lon
 
-   mesh.ec30to60.EC30to60Mesh
-   mesh.ec30to60.EC30to60Mesh.build_cell_width_lat_lon
+   mesh.ec30to60.EC30to60BaseMesh
+   mesh.ec30to60.EC30to60BaseMesh.build_cell_width_lat_lon
    mesh.ec30to60.dynamic_adjustment.EC30to60DynamicAdjustment
    mesh.ec30to60.dynamic_adjustment.EC30to60DynamicAdjustment.configure
    mesh.ec30to60.dynamic_adjustment.EC30to60DynamicAdjustment.run
 
-   mesh.qu240.QU240Mesh
-   mesh.qu240.QU240Mesh.build_cell_width_lat_lon
    mesh.qu240.dynamic_adjustment.QU240DynamicAdjustment
    mesh.qu240.dynamic_adjustment.QU240DynamicAdjustment.configure
    mesh.qu240.dynamic_adjustment.QU240DynamicAdjustment.run
 
-   mesh.so12to60.SO12to60Mesh
-   mesh.so12to60.SO12to60Mesh.build_cell_width_lat_lon
+   mesh.so12to60.SO12to60BaseMesh
+   mesh.so12to60.SO12to60BaseMesh.build_cell_width_lat_lon
    mesh.so12to60.dynamic_adjustment.SO12to60DynamicAdjustment
    mesh.so12to60.dynamic_adjustment.SO12to60DynamicAdjustment.configure
    mesh.so12to60.dynamic_adjustment.SO12to60DynamicAdjustment.run
 
-   mesh.wc14.WC14Mesh
-   mesh.wc14.WC14Mesh.build_cell_width_lat_lon
+   mesh.wc14.WC14BaseMesh
+   mesh.wc14.WC14BaseMesh.build_cell_width_lat_lon
    mesh.wc14.dynamic_adjustment.WC14DynamicAdjustment
    mesh.wc14.dynamic_adjustment.WC14DynamicAdjustment.configure
    mesh.wc14.dynamic_adjustment.WC14DynamicAdjustment.run
@@ -281,8 +274,8 @@ test cases and steps
    mesh.Mesh.configure
    mesh.Mesh.run
 
-   mesh.dequ120at30cr10rr2.DEQU120at30cr10rr2Mesh
-   mesh.dequ120at30cr10rr2.DEQU120at30cr10rr2Mesh.build_cell_width_lat_lon
+   mesh.dequ120at30cr10rr2.DEQU120at30cr10rr2BaseMesh
+   mesh.dequ120at30cr10rr2.DEQU120at30cr10rr2BaseMesh.build_cell_width_lat_lon
 
    init.Init
    init.Init.configure
@@ -669,6 +662,14 @@ ocean framework
 .. autosummary::
    :toctree: generated/
 
+   mesh.cull.CullMeshStep
+   mesh.cull.CullMeshStep.setup
+   mesh.cull.CullMeshStep.run
+   mesh.cull.cull_mesh
+
+   mesh.floodplain.FloodplainMeshStep
+   mesh.floodplain.FloodplainMeshStep.run
+
    haney.compute_haney_number
 
    iceshelf.compute_land_ice_pressure_and_draft

docs/developers_guide/ocean/framework.rst

@@ -37,6 +37,86 @@ and ``restingThickness`` variables for :ref:`ocean_z_level` and
 :ref:`ocean_z_star` coordinates using the ``ssh`` and ``bottomDepth`` as well
 as config options from ``vertical_grid``.
 
+.. _dev_ocean_framework_mesh:
+
+Mesh
+----
+
+The ``compass.ocean.mesh`` package includes modules for spherical ocean meshes
+shared across test groups.
+
+
+.. _dev_ocean_framework_cull_mesh:
+
+Culling Meshes
+~~~~~~~~~~~~~~
+
+The ``compass.ocean.mesh.cull`` module is for culling land cells from
+global ocean meshes.
+
+The class :py:class:`compass.ocean.mesh.cull.CullMeshStep` culls out land
+cells by calling ``cull_mesh()``.
+
+:py:func:`compass.ocean.mesh.cull.cull_mesh()` uses a number of
+capabilities from `MPAS-Tools <http://mpas-dev.github.io/MPAS-Tools/stable/>`_
+and `geometric_features <http://mpas-dev.github.io/geometric_features/stable/>`_
+to cull the mesh.  It performs the following steps:
+
+1. combining Natural Earth land coverage north of 60S with Antarctic
+   ice coverage or grounded ice coverage from BedMachineAntarctica
+
+2. combining transects defining critical passages (if
+   ``with_critical_passages=True``)
+
+3. combining points used to seed a flood fill of the global ocean.
+
+4. create masks from land coverage
+
+5. add land-locked cells to land coverage mask.
+
+6. create masks from transects (if ``with_critical_passages=True``)
+
+7. cull cells based on land coverage but with transects present
+
+8. create flood-fill mask based on seeds
+
+9. cull cells based on flood-fill mask
+
+10. create masks from transects on the final culled mesh (if
+    ``with_critical_passages=True``)
+
+
+.. _dev_ocean_framework_floodplain:
+
+Including a Floodplain
+~~~~~~~~~~~~~~~~~~~~~~
+
+The ``compass.ocean.mesh.floodplain`` module is for adding support for a
+floodplain to a base global ocean mesh.
+
+The class :py:class:`compass.ocean.mesh.floodplain.FloodplainMeshStep`
+descends from :py:class:`compass.mesh.QuasiUniformSphericalMeshStep`, adding
+an attribute:
+
+``self.preserve_floodplain``
+    A ``bool`` defining whether the mesh includes land cells
+
+and including topography in the base mesh from the
+`SRTM15_plus_earth_relief_15s.nc` file in the `bathymetry_database`.  The
+``run()`` method uses the config option:
+
+.. code-block:: ini
+
+    # options for spherical meshes
+    [spherical_mesh]
+
+    # Elevation threshold to use for including land cells
+    floodplain_elevation = 10.0
+
+to determine the elevation of the floodplain to maintain above sea level.
+The bathymetry and the floodplain are added to the mesh using
+:py:func:`mpas_tools.ocean.inject_bathymetry()` and
+:py:func:`mpas_tools.ocean.inject_preserve_floodplain()`, respectively.
 
 .. _dev_ocean_framework_haney:
 

docs/developers_guide/ocean/test_groups/global_ocean.rst

@@ -267,21 +267,10 @@ to improve model efficiency.
 A :py:class:`compass.ocean.tests.global_ocean.mesh.Mesh` object is constructed
 with the ``mesh_name`` as one of its arguments.  Based on this argument, it
 determines the appropriate child class of
-:py:class:`compass.ocean.tests.global_ocean.mesh.mesh.MeshStep` to create.
+:py:class:`compass.mesh.spherical.SphericalBaseStep` to create the base mesh
+and adds a :py:class:`compass.ocean.mesh.cull.CullMeshStep`.
 
-.. _dev_ocean_global_ocean_mesh_step:
-
-mesh step
-^^^^^^^^^
-
-The parent class :py:class:`compass.ocean.tests.global_ocean.mesh.mesh.MeshStep`
-defines a method
-:py:meth:`compass.ocean.tests.global_ocean.mesh.mesh.MeshStep.build_cell_width_lat_lon()`
-that a child class for each mesh type must override to define the size of
-MPAS cells as a function of longitude and latitude.
-
-This class also takes care of defining the output from the step and storing
-attributes:
+This class also stores attributes:
 
 ``self.mesh_name``
     the name of the mesh
@@ -296,39 +285,6 @@ attributes:
 ``self.mesh_config_filename``
     the name of the config file with mesh-specific config options
 
-In its ``run()`` method, ``MeshStep`` calls the ``build_cell_width_lat_lon()``
-method to get the desired mesh resolution, then creates the mesh by calling
-:py:func:`mpas_tools.ocean.build_mesh.build_spherical_mesh()` culls out land
-cells by calling :py:func:`compass.ocean.tests.global_ocean.mesh.cull.cull_mesh()`.
-
-``cull_mesh()`` uses a number of capabilities from
-`MPAS-Tools <http://mpas-dev.github.io/MPAS-Tools/stable/>`_
-and `geometric_features <http://mpas-dev.github.io/geometric_features/stable/>`_
-to cull the mesh.  It performs the following steps:
-
-1. combining Natural Earth land coverage north of 60S with Antarctic
-   ice coverage or grounded ice coverage from BedMachineAntarctica
-
-2. combining transects defining critical passages (if
-   ``with_critical_passages=True``)
-
-3. combining points used to seed a flood fill of the global ocean.
-
-4. create masks from land coverage
-
-5. add land-locked cells to land coverage mask.
-
-6. create masks from transects (if ``with_critical_passages=True``)
-
-7. cull cells based on land coverage but with transects present
-
-8. create flood-fill mask based on seeds
-
-9. cull cells based on flood-fill mask
-
-10. create masks from transects on the final culled mesh (if
-    ``with_critical_passages=True``)
-
 .. _dev_ocean_global_ocean_meshes:
 
 meshes
@@ -343,12 +299,12 @@ QU240 and QUwISC240
 
 The ``QU240`` mesh is a quasi-uniform mesh with 240-km resolution. The
 ``QUwISC240`` mesh is identical except that it includes the cavities below ice
-shelves in the ocean domain. The class
-:py:class:`compass.ocean.tests.global_ocean.mesh.qu240.QU240Mesh` defines the
-resolution for both meshes. The ``compass.ocean.tests.global_ocean.mesh.qu240``
-module includes namelist options appropriate for forward simulations with both
-RK4 and split-explicit time integration on this mesh.  These set the time step
-and default run duration for short runs with this mesh.
+shelves in the ocean domain. The mesh is defined by
+:py:class:`compass.mesh.QuasiUniformSphericalMeshStep`.  The
+``compass.ocean.tests.global_ocean.mesh.qu240`` module includes namelist
+options appropriate for forward simulations with both RK4 and split-explicit
+time integration on this mesh.  These set the time step and default run
+duration for short runs with this mesh.
 
 The default config options for this mesh are:
 
@@ -419,6 +375,17 @@ The default config options for this mesh are:
 The vertical grid is a ``tanh_dz`` profile (see :ref:`dev_ocean_framework_vertical`)
 with 16 vertical levels ranging in thickness from 3 to 500 m.
 
+.. _dev_ocean_global_ocean_isco240:
+
+Icos240 and IcoswISC240
++++++++++++++++++++++++
+
+The ``Icos240`` mesh is a subdivided icosahedral mesh with 240-km resolution
+using the :py:class:`compass.mesh.IcosahedralMeshStep` class. The
+``IcoswISC240`` mesh is identical except that it includes the cavities below
+ice shelves in the ocean domain. Aside from the base mesh, these are identical
+to :ref:`dev_ocean_global_ocean_qu240`.
+
 .. _dev_ocean_global_ocean_ec30to60:
 
 EC30to60 and ECwISC30to60