Merge pull request #284 from andrewdnolan/merry_go_round

The merry-go-round test group is used for testing the vertical advection scheme only using tracers. This PR ports the `Default` test case from the `merry_go_round` test group from `compass`. This PR also adds convergence tests in space and both space and time.

Author: cbegeman

docs/developers_guide/ocean/api.md

@@ -260,6 +260,35 @@
    viz.Viz.run
 ```
 
+### merry_go_round
+
+```{eval-rst}
+.. currentmodule:: polaris.tasks.ocean.merry_go_round
+
+.. autosummary::
+   :toctree: generated/
+
+   add_merry_go_round_tasks
+
+   default.Default
+   default.viz.Viz
+   default.viz.Viz.setup
+   default.viz.Viz.run
+
+   forward.Forward
+   forward.Forward.compute_cell_count
+
+   init.Init
+   init.Init.setup
+   init.Init.run
+
+   analysis.Analysis
+
+   viz.Viz
+   viz.Viz.setup
+   viz.Viz.run
+```
+
 ### overflow
 
 ```{eval-rst}

docs/developers_guide/ocean/tasks/index.md

@@ -16,6 +16,7 @@ ice_shelf_2d
 inertial_gravity_wave
 internal_wave
 manufactured_solution
+merry_go_round
 nondivergent_2d
 overflow
 rotation_2d

docs/developers_guide/ocean/tasks/merry_go_round.md

@@ -0,0 +1,81 @@
+(dev-ocean-merry-go-round)=
+
+# merry-go-round
+
+The merry-go-round task group is currently comprised of one `default` task for
+quick testing and two convergence tests testing the convergence in space
+and both space and time.
+
+## framework
+
+The shared config options for `merry_go_round` tests  are described in
+{ref}`ocean-merry-go-round` in the User's Guide.
+
+Additionally, the tests share a `forward.yaml` file with a few common model
+config options related to time management, time integration, and which
+tendencies terms are active, as well as defining `mesh`, `input`, `restart`,
+and `output` streams.
+
+### init
+
+The class {py:class}`polaris.tasks.ocean.merry_go_round.init.Init`
+defines a step for setting up the initial state for each test case.
+
+First, a mesh appropriate for the resolution is generated using
+{py:func}`mpas_tools.planar_hex.make_planar_hex_mesh()`.  Then, the mesh is
+culled to remove periodicity in the y direction. The uniform bottom depth and
+requested number of vertical layer (default of 50) are used to define a
+vertical coordinate. Next, the ocean state is generated following the
+initial condition description from {ref}`ocean-merry-go-round` in the User's
+Guide.
+
+### forward
+
+The class {py:class}`polaris.tasks.ocean.merry_go_round.forward.Forward`
+defines a step for running the ocean model from the initial condition produced
+in the `init` step. The time step is determined algorithmically based on
+config options (i.e. `dt_per_km`) and the type of refinement requested. The
+number of cells is approximated from config options in
+{py:meth}`polaris.tasks.ocean.merry_go_round.forward.Forward.compute_cell_count()`
+so that this can be used to constrain the number of MPI tasks that Polaris
+tasks have as their target and minimum (if the resources are not explicitly
+prescribed).  For MPAS-Ocean, PIO namelist options are modified and a
+graph partition is generated as part of `runtime_setup()`.  Next, the ocean
+model is run. The duration is set by `run_duration` in the config section
+corresponding to the task (`merry_go_round`). Finally, validation of
+`normalVelocity`, `tracer1`, `tracer2`, and `tracer3` in the `output.nc`
+file are performed against a baseline if one is provided when
+calling {ref}`dev-polaris-setup`.
+
+(dev-ocean-merry-go-round)=
+
+## default
+
+The {py:class}`polaris.tasks.ocean.merry_go_round.default.Default`
+test runs the `init` step, the `forward` step, and a custom `viz` step.
+
+### viz
+
+The {py:class}`polaris.tasks.ocean.merry_go_round.default.viz.Viz` plots
+transects of the horizontal velocity, vertical velocity, simulated tracer
+concentration, and error in simulated tracer concentration at the end of the
+forward run. This more detailed plotting step is only available for the
+default test case.
+
+(dev-ocean-merry-go-analysis)=
+
+## convergence tasks
+
+### analysis
+
+The class {py:class}`polaris.tasks.ocean.merry_go_round.analysis.Analysis`
+descends from {py:class}`polaris.ocean.convergence.analysis.ConvergenceAnalysis`
+a step for computing the error from the final simulated field
+and the exact solution. It uses the config options to determine whether the
+convergence rate falls within acceptable bounds.
+
+### viz
+
+The class {py:class}`polaris.tasks.ocean.merry_go_round.viz.Viz`
+defines a step for visualization. It produces transects of the simulated,
+exact, and (simulated - exact) `tracer1` fields for each resolution.

docs/users_guide/ocean/tasks/images/merry_go_round_convergence.png

@@ -16,6 +16,7 @@ ice_shelf_2d
 inertial_gravity_wave
 internal_wave
 manufactured_solution
+merry_go_round
 nondivergent_2d
 overflow
 rotation_2d

docs/users_guide/ocean/tasks/images/merry_go_round_section.png

@@ -0,0 +1,174 @@
+(ocean-merry-go-round)=
+
+# merry-go-round
+
+The `ocean/merry_go_round` test group induces a convective cell in a horizontal
+domain in order to verify tracer advection.
+
+```{image} images/merry_go_round_section.png
+:align: center
+:width: 500 px
+```
+
+## supported models
+
+These tasks only support MPAS-Ocean.
+
+(ocean-merry-go-round-default)=
+
+## default
+
+### description
+
+For the initial conditions described below, tracer concentration contours match
+the streamlines of the convective cell, such that an accurate tracer advection
+scheme would result in no change in the tracer field in time.
+
+The init step generates the mesh and initial condition for the requested
+resolution.
+
+The forward step runs the model for the requested length of time. Tendencies
+for normal velocity and layer thickness are disabled, such that these fields
+remain fixed at their initial conditions throughout the simulation.
+
+The visualization step produces a plot illustrating the horizontal velocity,
+vertical velocity, simulated `tracer1` concentration, the error in simulated
+tracer concentration at the end of the forward simulation.
+(See above for an example).
+
+### mesh
+The mesh is planar and the resolution is specified by config option
+`merry_go_round_default:resolution`, which defaults to 5 m. The horizontal
+dimensions of the domain are set by config options `merry_go_round:lx` and
+`merry_go_round:ly`, defaulting to 500 m by 5 m. The domain is solid on the
+zonal boundaries and periodic on the meridional boundaries.
+
+### vertical grid
+
+The vertical coordinate is fixed throughout the simulation.
+
+```cfg
+[vertical_grid]
+
+# the type of vertical grid
+grid_type = uniform
+
+# Number of vertical levels for base resolution
+vert_levels = 50
+
+# Depth of the bottom of the ocean
+bottom_depth = 500.0
+
+# The type of vertical coordinate (e.g. z-level, z-star)
+coord_type = z-level
+
+# Whether to use "partial" or "full", or "None" to not alter the topography
+partial_cell_type = None
+
+# The minimum fraction of a layer for partial cells
+min_pc_fraction = 0.1
+```
+
+### initial conditions
+
+Salinity is constant throughout the domain as specified by
+`merry_go_round:salinity_background`, which defaults to 35 PSU. The initial
+temperature is high on the right side (`merry_go_round:temperature_right`) of
+and low on the left side (`merry_go_round:temperature_left`) of the domain,
+with defaults of 30 degC and 5 degC respectively. This field initiates
+a convective cell in the zonal and vertical dimensions. Debug tracer, `tracer1`
+, is initialized with a high value in the center of domain and gradually
+transitions to a lower value at the edges of the domain.
+
+### forcing
+N/A
+
+### time step and run duration
+
+The time step is determined by the config option `merry_go_round:dt_per_km`
+according to the mesh resolution (i.e. `convergence:base_resolution`).
+The run duration is determined by the config option
+`merry_go_round:run_duration` as measured in hours.
+
+### config options
+
+The following config options are available for this case:
+
+```cfg
+[merry_go_round]
+
+# the size of the domain in km in the x direction
+lx = 0.5
+
+# the size of the domain in km in the y direction
+ly = 0.005
+
+# temperature on the right of the domain
+temperature_right = 30.
+
+# temperature on the left of the domain
+temperature_left = 5.
+
+# background salinity
+salinity_background = 35.
+
+# background tracer2 concentration
+tracer2_background = 10.
+
+# background tracer3 concentration
+tracer3_background = 20.
+
+# Time step per resolution (s/km), since dt is proportional to resolution
+dt_per_km = 72000.0
+
+# Convergence threshold below which the test fails
+conv_thresh = 1.2
+
+# Run duration in hours
+run_duration = 6.
+
+[merry_go_round_default]
+# the mesh resolution (km) at which the default test case is run and
+# the resolution to which refinement_factors are applied if refinement is
+# 'space' or 'both' on a planar mesh
+resolution = 0.005
+```
+
+### cores
+
+The number of cores is determined according to the config options
+``max_cells_per_core`` and ``goal_cells_per_core``.
+
+(ocean-merry-go-round-convergence)=
+
+## convergence tasks
+
+There are two versions of the convergence test case: `convergence_space` and 
+`convergence_both` corresponding to space and both space and time convergence
+tests. All settings are the same as the
+{ref}`ocean-merry-go-round-default` case, but now the resolution and/or time step
+are refined to asses the order of convergence for tracer advection. Tests
+involving spatial convergence have a horizontal resolution of
+`convergence:base_resolution` times `convergence:refinement_factors_space`.
+Tests invoking both spatial and temporal convergence refine the spatial
+resolution as described above and use a time step set by
+`merry_go_round:dt_per_km` times the refined spatial resolution
+(see {ref}`dev-ocean-convergence` for more details on how to change resolutions
+or time steps tested).
+
+The init and forward steps are analogous to what is described above for
+{ref}`ocean-merry-go-round-default`.
+
+The analysis step computes the `convergence:error_type` of your choosing,
+between the simulated `tracer1` field and the exact solution at the end
+of the simulation. Because tracer concentration contours match the streamlines
+of the convective cell the exact solution is equivalent to the initial
+condition. It also computes the convergence rate with resolution and/or
+time step, producing a plot like:
+
+```{image} images/merry_go_round_convergence.png
+:align: center
+:width: 500 px
+```
+The visualization step plot the numerical solution, exact solution, and their
+difference for each resolution and/or time step simulated.

docs/users_guide/ocean/tasks/index.md

@@ -56,6 +56,10 @@ class ConvergenceAnalysis(OceanIOStep):
     refinement : str
         Refinement type. One of 'space', 'time' or 'both' indicating both
         space and time
+
+    mesh_filename : str
+        The name of the mesh file to use for calculating mesh metrics
+        (i.e. cell area) needed for computing the error
     """
 
     def __init__(
@@ -65,6 +69,7 @@ def __init__(
         dependencies,
         convergence_vars,
         refinement='both',
+        mesh_filename='base_mesh.nc',
     ):
         """
         Create the step
@@ -114,11 +119,17 @@ def __init__(
         refinement : str, optional
             Refinement type. One of 'space', 'time' or 'both' indicating both
             space and time
+
+        mesh_filename : str
+            The name of the mesh file to use for calculating mesh metrics
+            (i.e. cell area) needed for computing the error
         """
         super().__init__(component=component, name='analysis', subdir=subdir)
+
         self.dependencies_dict = dependencies
         self.convergence_vars = convergence_vars
         self.refinement = refinement
+        self.mesh_filename = mesh_filename
 
         for var in convergence_vars:
             self.add_output_file(f'convergence_{var["name"]}.png')
@@ -137,12 +148,12 @@ def setup(self):
             option = 'refinement_factors_space'
         refinement_factors = config.getlist('convergence', option, dtype=float)
         for refinement_factor in refinement_factors:
-            base_mesh = dependencies['mesh'][refinement_factor]
+            mesh = dependencies['mesh'][refinement_factor]
             init = dependencies['init'][refinement_factor]
             forward = dependencies['forward'][refinement_factor]
             self.add_input_file(
                 filename=f'mesh_r{refinement_factor:02g}.nc',
-                work_dir_target=f'{base_mesh.path}/base_mesh.nc',
+                work_dir_target=f'{mesh.path}/{self.mesh_filename}',
             )
             self.add_input_file(
                 filename=f'init_r{refinement_factor:02g}.nc',

docs/users_guide/ocean/tasks/merry_go_round.md

@@ -2,6 +2,7 @@ ocean/planar/inertial_gravity_wave/convergence_both
 ocean/planar/manufactured_solution/convergence_both/default
 ocean/planar/manufactured_solution/convergence_both/del2
 ocean/planar/manufactured_solution/convergence_both/del4
+ocean/planar/merry_go_round/convergence_both
 ocean/spherical/icos/correlated_tracers_2d
   cached: icos_base_mesh_60km icos_base_mesh_120km icos_base_mesh_240km icos_base_mesh_480km
 ocean/spherical/qu/correlated_tracers_2d

polaris/ocean/convergence/analysis.py

@@ -7,6 +7,7 @@ ocean/planar/inertial_gravity_wave/convergence_both
 ocean/planar/internal_wave/standard/default
 ocean/planar/internal_wave/vlr/default
 # ocean/planar/manufactured_solution/convergence_both
+# ocean/planar/merry_go_round/default
 ocean/planar/overflow/default
 ocean/single_column/cvmix
 ocean/single_column/ekman