Merge pull request #126 from cbegeman/ocn-shared-convergence-analysis…

…-step

Shared ocean spherical convergence analysis step

docs/developers_guide/ocean/api.md

@@ -104,8 +104,7 @@
    forward.Forward.dynamic_model_config
 
    analysis.Analysis
-   analysis.Analysis.run
-   analysis.Analysis.rmse
+   analysis.Analysis.exact_solution
 
    viz.VizMap
    viz.VizMap.run
@@ -178,6 +177,12 @@
    :toctree: generated/
 
    SphericalConvergenceForward
+   SphericalConvergenceAnalysis
+   SphericalConvergenceAnalysis.compute_error
+   SphericalConvergenceAnalysis.convergence_parameters
+   SphericalConvergenceAnalysis.exact_solution
+   SphericalConvergenceAnalysis.run
+   SphericalConvergenceAnalysis.plot_convergence
 ```
 
 ### Ocean Model

docs/developers_guide/ocean/framework.md

@@ -159,6 +159,12 @@ qu_resolutions = 60, 90, 120, 150, 180, 210, 240
 # Evaluation time for convergence analysis (in days)
 convergence_eval_time = 1.0
 
+# Convergence threshold below which a test fails
+convergence_thresh = 1.0
+
+# Type of error to compute
+error_type = l2
+
 
 # config options for spherical convergence forward steps
 [spherical_convergence_forward]
@@ -183,14 +189,19 @@ run_duration = ${spherical_convergence:convergence_eval_time}
 output_interval = ${run_duration}
 ```
 The first 2 are the default resolutions for icosahedral and quasi-uniform
-base meshes, respectively.  The `time_integrator` will typically be overridden
-by the specific convergence task's config options, and indicates which time
-integrator to use for the forward run.  Depending on the time integrator,
-either `rk4_dt_per_km` or `split_dt_per_km` will be used to determine an
-appropriate time step for each mesh resolution (proportional to the cell size).
-For split time integrators, `btr_dt_per_km` will be used to compute the
-barotropic time step in a similar way.  The `run_duration` and 
-`output_interval` are typically the same, and they are given in days.
+base meshes, respectively.  The `convergence_eval_time` will generally be
+modified by each test case. The `convergence_thresh` will also be modified by
+each test case, and will depend on the numerical methods being tested. The
+`error_type` is the L2 norm by default.
+
+`time_integrator` will typically be overridden by the specific convergence
+task's config options, and indicates which time integrator to use for the
+forward run.  Depending on the time integrator, either `rk4_dt_per_km` or
+`split_dt_per_km` will be used to determine an appropriate time step for each
+mesh resolution (proportional to the cell size). For split time integrators,
+`btr_dt_per_km` will be used to compute the barotropic time step in a similar
+way.  The `run_duration` and `output_interval` are typically the same, and
+they are given in days.
 
 Each convergence test can override these defaults with its own defaults by 
 defining them in its own config file.  Convergence tests should bring in this
@@ -311,6 +322,57 @@ omega:
 on the associated config options (first at setup and again at runtime in case
 the config options have changed).
 
+In addition, the {py:class}`polaris.ocean.convergence.spherical.SphericalConvergenceAnalysis`
+step can serve as a parent class for analysis steps in convergence tests.  This
+parent class computes the error norm for the output from each resolution's
+forward step. It also produces the convergence plot.
+
+This is an example of how a task's analysis step can descend from the parent
+class:
+
+```python
+class Analysis(SphericalConvergenceAnalysis):
+    """
+    A step for analyzing the output from the cosine bell test case
+    """
+    def __init__(self, component, resolutions, icosahedral, subdir,
+                 dependencies):
+        """
+        Create the step
+
+        Parameters
+        ----------
+        component : polaris.Component
+            The component the step belongs to
+
+        resolutions : list of float
+            The resolutions of the meshes that have been run
+
+        icosahedral : bool
+            Whether to use icosahedral, as opposed to less regular, JIGSAW
+            meshes
+
+        subdir : str
+            The subdirectory that the step resides in
+
+        dependencies : dict of dict of polaris.Steps
+            The dependencies of this step
+        """
+        convergence_vars = [{'name': 'tracer1',
+                             'title': 'tracer1',
+                             'zidx': 0}]
+        super().__init__(component=component, subdir=subdir,
+                         resolutions=resolutions,
+                         icosahedral=icosahedral,
+                         dependencies=dependencies,
+                         convergence_vars=convergence_vars)
+```
+
+Many tasks will also need to override the `exact_solution` method given in
+{py:class}`polaris.ocean.convergence.spherical.SphericalConvergenceAnalysis`.
+If not overridden, the analysis step will compute the difference of the output
+from the initial state.
+
 (dev-ocean-framework-vertical)=
 
 ## Vertical coordinate

docs/developers_guide/ocean/tasks/cosine_bell.md

@@ -44,8 +44,11 @@ section.  Other model config options are taken from `forward.yaml`.
 ### analysis
 
 The class {py:class}`polaris.ocean.tasks.cosine_bell.analysis.Analysis`
-defines a step for computing the RMSE (root-mean-squared error) for the results
-at each resolution and plotting them in `convergence.png`.
+descends from
+{py:class}`polaris.ocean.convergence.spherical.SphericalConvergenceAnalysis`,
+and defines a step for computing the error norm (L2) for the results
+at each resolution, saving them in `convergence_tracer1.csv` and plotting them
+in `convergence_tracer1.png`.
 
 ### viz
 

docs/users_guide/ocean/tasks/cosine_bell.md

@@ -176,12 +176,6 @@ The convergence_eval_time, run duration and output interval are the period for
 advection to make a full rotation around the globe, 24 days:
 
 ```cfg
-# config options for spherical convergence tests
-[spherical_convergence]
-
-# Evaluation time for convergence analysis (in days)
-convergence_eval_time = ${cosine_bell:vel_pd}
-
 # config options for spherical convergence tests
 [spherical_convergence_forward]
 
@@ -192,7 +186,7 @@ run_duration = ${cosine_bell:vel_pd}
 output_interval = ${cosine_bell:vel_pd}
 ```
 
-Her, `${cosine_bell:vel_pd}` means that the same value is used as in the 
+Here, `${cosine_bell:vel_pd}` means that the same value is used as in the 
 option `vel_pd` in section `[cosine_bell]`, see below.
 
 ## config options
@@ -224,17 +218,8 @@ psi0 = 1.0
 # time (days) for bell to transit equator once
 vel_pd = 24.0
 
-# convergence threshold below which the test fails for QU meshes
-qu_conv_thresh = 1.8
-
-# Convergence rate above which a warning is issued for QU meshes
-qu_conv_max = 2.2
-
-# convergence threshold below which the test fails for icosahedral meshes
-icos_conv_thresh = 1.8
-
-# Convergence rate above which a warning is issued for icosahedral meshes
-icos_conv_max = 2.2
+# convergence threshold below which the test fails
+convergence_thresh = 1.8
 
 
 # options for visualization for the cosine bell convergence test case
@@ -270,6 +255,21 @@ when the convergence rates are not within the expected range.
 The options in the `cosine_bell_viz` section are used in visualizing the
 initial and final states on a lon-lat grid for `cosine_bell/with_viz` tasks.
 
+By default, the convergence analysis step analyzes convergence after the
+cosine bell has circulated the globe once. It also computes the L2 norm. Both
+of these config options can be changed here:
+
+```cfg
+# config options for spherical convergence tests
+[spherical_convergence]
+
+# Evaluation time for convergence analysis (in days)
+convergence_eval_time = ${cosine_bell:vel_pd}
+
+# Type of error to compute
+error_type = l2
+```
+
 ## cores
 
 The target and minimum number of cores are determined by `goal_cells_per_core`

polaris/ocean/convergence/spherical/__init__.py

@@ -1,3 +1,6 @@
+from polaris.ocean.convergence.spherical.analysis import (
+    SphericalConvergenceAnalysis,
+)
 from polaris.ocean.convergence.spherical.forward import (
     SphericalConvergenceForward,
 )