Update docs

compass/ocean/tests/drying_slope/analysis.py

@@ -11,17 +11,42 @@
 
 class Analysis(Step):
     """
-    A step for visualizing drying slope results, as well as comparison with
-    analytical solution and ROMS results.
+    A step for analyzing the convergence of drying slope results and producing
+    a convergence plot.
 
     Attributes
     ----------
+    damping_coeff : float
+        The Rayleigh damping coefficient used for the forward runs
+
+    resolutions : float
+        The resolution of the test case
+
+    times : list of float
+        The times at which to compare to the analytical solution
     """
     def __init__(self, test_case, resolutions, damping_coeff):
+        """
+        Create a forward step
+
+        Parameters
+        ----------
+        test_case : compass.TestCase
+            The test case this step belongs to
+
+        resolutions : list of floats
+            The resolution of the test case
+
+        damping_coeff: float
+            the value of the rayleigh damping coefficient
+        """
+
         super().__init__(test_case=test_case, name='analysis')
+
         self.damping_coeff = damping_coeff
         self.resolutions = resolutions
         self.times = ['0.05', '0.15', '0.25', '0.30', '0.40', '0.50']
+
         for resolution in resolutions:
             if resolution < 1.:
                 res_name = f'{int(resolution*1e3)}m'
@@ -34,12 +59,33 @@ def __init__(self, test_case, resolutions, damping_coeff):
                        '.csv'
             self.add_input_file(filename=filename, target=filename,
                                 database='drying_slope')
+
         self.add_output_file(filename='convergence.png')
 
     def run(self):
+        """
+        Run this step of the test case
+        """
         self._plot_convergence()
 
     def _compute_rmse(self, ds, t):
+        """
+        Get the time step
+
+        Parameters
+        ----------
+        ds : xarray.Dataset
+            the MPAS dataset containing output from a forward step
+        t : float
+            the time to evaluate the RMSE at
+
+        Returns
+        -------
+        rmse : float
+            the root-mean-squared-error of the MPAS output relative to the
+            analytical solution at time t
+        """
+
         x_exact, ssh_exact = self._exact_solution(t)
         tidx = int((float(t) / 0.2 + 1e-16) * 24.0)
         ds = ds.drop_vars(np.setdiff1d([j for j in ds.variables],
@@ -61,7 +107,6 @@ def _plot_convergence(self):
         """
         Plot convergence curves
         """
-
         comparisons = []
         cases = {'standard': '../../../standard/convergence/analysis',
                  'ramp': '../../../ramp/convergence/analysis'}
@@ -115,7 +160,7 @@ def _plot_convergence(self):
 
     def _exact_solution(self, time):
         """
-        Returns distance, ssh
+        Returns distance, ssh of the analytic solution
         """
         datafile = f'./r{self.damping_coeff}d{time}-'\
                    f'analytical.csv'

compass/ocean/tests/drying_slope/convergence/__init__.py

@@ -9,7 +9,7 @@
 
 class Convergence(TestCase):
     """
-    The default drying_slope test case
+    The convergence drying_slope test case
 
     Attributes
     ----------
@@ -18,6 +18,10 @@ class Convergence(TestCase):
 
     coord_type : str
         The type of vertical coordinate (``sigma``, ``single_layer``, etc.)
+
+    damping_coeffs: list of float
+        The damping coefficients at which to evaluate convergence. Must be of
+        length 1.
     """
 
     def __init__(self, test_group, coord_type, method):
@@ -31,6 +35,9 @@ def __init__(self, test_group, coord_type, method):
 
         coord_type : str
             The type of vertical coordinate (``sigma``, ``single_layer``)
+
+        method: str
+            The wetting-and-drying method (``standard``, ``ramp``)
         """
         name = 'convergence'
 

compass/ocean/tests/drying_slope/forward.py

@@ -14,7 +14,7 @@ def __init__(self, test_case, resolution, name='forward', subdir=None,
                  ntasks=1, min_tasks=None, openmp_threads=1,
                  damping_coeff=None, coord_type='sigma'):
         """
-        Create a new test case
+        Create a forward step
 
         Parameters
         ----------

docs/developers_guide/ocean/api.rst

@@ -87,8 +87,13 @@ drying_slope
 
    DryingSlope
 
+   analysis.Analysis
+   analysis.Analysis.run
+
+   convergence.Convergence
+   convergence.Convergence.validate
+
    default.Default
-   default.Default.configure
    default.Default.validate
 
    forward.Forward
@@ -108,7 +113,6 @@ drying_slope
    viz.Viz
    viz.Viz.run
 
-
 global_convergence
 ~~~~~~~~~~~~~~~~~~
 

docs/developers_guide/ocean/test_groups/drying_slope.rst

@@ -22,8 +22,8 @@ duration, bottom drag, and tidal forcing options, as well as shared
 ``streams.init`` and ``streams.forward`` files that defines ``mesh``, ``input``,
 ``restart``, ``forcing`` and ``output`` streams.
 
-Namelist options specific to resolutions and vertical coordinates are given in
-``namelist.${RES}.*`` and ``namelist.${COORD}*`` files.
+Namelist options specific vertical coordinates are given in
+``namelist.${COORD}*`` files.
 
 initial_state
 ~~~~~~~~~~~~~
@@ -66,6 +66,13 @@ between the analytical solution, MPAS-Ocean and ROMS. Similar plots are used
 to create a movie showing the solution from MPAS-Ocean at more fine-grained
 time intervals. 
 
+analysis
+~~~~~~~~
+
+The class :py:class:`compass.ocean.tests.drying_slope.analysis.Analysis`
+produces a convergence plot for a series of forward steps at different
+resolutions. It uses the analytical solution available at 5 discrete times t
+compute the RMSE.
 
 .. _dev_ocean_drying_slope_default:
 
@@ -81,16 +88,13 @@ two cases at different values of ``config_Rayleigh_damping_coeff``, 0.0025 and
 0.01, for which there is comparison data. The ``single_layer`` case runs at one
 value of the implicit bottom drag coefficient. 
 
+.. _dev_ocean_drying_slope_convergence:
 
-.. _dev_ocean_drying_slope_ramp:
-
-ramp
-----
-
-The :py:class:`compass.ocean.tests.drying_slope.ramp.Ramp` is identical to the
-default class except it sets ``ramp`` to ``True`` for the forward step to enable
-the ramp feature for wetting and drying.
+convergence
+-----------
 
+The :py:class:`compass.ocean.tests.drying_slope.convergence.Convergence` expands
+on the default class to include initial and forward steps for multiple resolutoins and an analysis step to generate a convergence plot.
 
 .. _dev_ocean_drying_slope_log_law:
 

docs/users_guide/ocean/test_groups/drying_slope.rst

@@ -64,6 +64,14 @@ The config options for this test case are:
    # the number of grid cells in x and y
    nx = 6
    
+   # time step in s per km of horizontal resolution
+   dt_per_km = 30
+   
+   # config options for visualizing drying slope ouptut
+   [drying_slope_convergence]
+   
+   resolutions = 0.25, 0.5, 1, 2
+
    # config options for visualizing drying slope ouptut
    [drying_slope_viz]
    
@@ -81,21 +89,24 @@ All units are mks.
 default
 -------
 
-``ocean/drying_slope/${RES}/${COORD}/default`` is the default version of the
-drying slope test case for two short (12h) test runs with two different drag
-coefficients and validation of sea surface height through visual inspection
+``ocean/drying_slope/${COORD}/${METHOD}/${RES}/default`` is the default version
+of the drying slope test case for two short (12h) test runs with two different
+drag coefficients and validation of sea surface height through visual inspection
 against analytic and ROMS solutions. ``RES`` is either 250m or 1km. ``COORD``
-is either ``single_layer`` or ``sigma``. Rayleigh drag is not compatible with
-``single_layer`` so implicit drag with a constant coefficient is used.
-
-ramp
-----
-
-``ocean/drying_slope/${RES}/${COORD}/ramp`` is identical to the ``default``
-test except the factor that scales velocities and velocity tendencies is
-ramped over a given layer thickness range rather than a binary switch at the
-minimum thickness. ``RES`` is either 250m or 1km. ``COORD`` is either
-``single_layer`` or ``sigma``.
+is either ``single_layer`` or ``sigma``. The wetting and drying ``METHOD`` is
+either ``standard`` or ``ramp``. The ``ramp`` method ramps velocities and
+velocity tendencies over a given layer thickness range rather than a binary
+switch at the minimum thickness.
+
+convergence
+-----------
+
+``ocean/drying_slope/${COORD}/${METHOD}/convergence`` is a convergence test in
+horizontal resolution and time. It produces a convergence plot for the
+resolutions specified in the config file. ``COORD`` is either ``single_layer``
+or ``sigma``. The wetting and drying ``METHOD`` is either ``standard`` or
+``ramp``. If the other of the two methods has already been run, its convergence
+curve will be included in the plot.
 
 loglaw
 ------