Merge pull request #120 from xylar/add-geostrophic-tests

Add geostrophic convergence test (Williamson Test 2)

docs/developers_guide/ocean/api.md

@@ -113,6 +113,35 @@
    viz.Viz.run
 ```
 
+### geostrophic
+
+```{eval-rst}
+.. currentmodule:: polaris.ocean.tasks.geostrophic
+
+.. autosummary::
+   :toctree: generated/
+
+   add_geostrophic_tasks
+
+   Geostrophic
+   Geostrophic.configure
+
+   init.Init
+   init.Init.run
+
+   forward.Forward
+
+   analysis.Analysis
+   analysis.Analysis.run
+   analysis.Analysis.compute_rmse
+
+   viz.VizMap
+   viz.VizMap.run
+
+   viz.Viz
+   viz.Viz.run
+```
+
 ### manufactured_solution
 
 ```{eval-rst}

docs/developers_guide/ocean/tasks/cosine_bell.md

@@ -2,7 +2,7 @@
 
 # cosine_bell
 
-The {py:class}`polaris.ocean.tasks.global_convergence.cosine_bell.CosineBell`
+The {py:class}`polaris.ocean.tasks.cosine_bell.CosineBell`
 test performs a series of 24-day runs that advect a bell-shaped tracer blob
 around the sphere.  The resolution of the sphere varies (by default, between
 60 and 240 km).  Advected results are compared with a known exact solution to

docs/developers_guide/ocean/tasks/geostrophic.md

@@ -0,0 +1,65 @@
+(dev-ocean-geostrophic)=
+
+# geostrophic
+
+The {py:class}`polaris.ocean.tasks.geostrophic.Geostrophic`
+test performs a series of 5-day runs starting from an initial condition in
+geostrophic balance.  The resolution of the sphere varies (by default, between
+60 and 240 km).  The results after 5 days are compared with the exact solution
+used to produce the initial condition to determine the rate of convergence.
+
+## framework
+
+The config options for the `geostrophic` tests are described in 
+{ref}`ocean-geostrophic` in the User's Guide.
+
+Additionally, the test uses a `forward.yaml` file with a few common
+model config options related to drag and default horizontal and
+vertical momentum and tracer diffusion, as well as defining `mesh`, `input`,
+`restart`, and `output` streams.
+
+### base_mesh
+
+Geostrophic tasks use shared `base_mesh` steps for creating
+{ref}`dev-ocean-spherical-meshes` at a sequence of resolutions.
+
+### init
+
+The class {py:class}`polaris.ocean.tasks.geostrophic.init.Init`
+defines a step for setting up the initial state at each resolution with a
+velocity field and water-column thickness in geostrophic balance, as described
+in {ref}`ocean-geostrophic-init` in the User's Guide.
+
+### forward
+
+The class {py:class}`polaris.ocean.tasks.geostrophic.forward.Forward`
+descends from {py:class}`polaris.ocean.convergence.spherical.SphericalConvergenceForward`,
+and defines a step for running MPAS-Ocean from an initial condition produced in
+an `init` step. See {ref}`dev-ocean-spherical-convergence` for some relevant
+discussion of the parent class. The time step is determined from the resolution
+based on the `dt_per_km` config option in the `[spherical_convergences]` 
+section.  Other model config options are taken from `forward.yaml`.
+
+### analysis
+
+The class {py:class}`polaris.ocean.tasks.geostrophic.analysis.Analysis`
+defines a step for 
+
+### viz
+
+Two visualization steps are available only in the `geostrophic/with_viz`
+tasks.  They are not included in the `geostrophic` in order to keep regression
+as fast as possible when visualization isn't needed.
+
+The class {py:class}`polaris.ocean.tasks.geostrophic.viz.VizMap`
+defines a step for creating a mapping file from the MPAS mesh at a given
+resolution to a lon-lat grid at a resolution and interpolation method 
+determined by config options shown in {ref}`ocean-geostrophic-config`.
+
+The class {py:class}`polaris.ocean.tasks.geostrophic.viz.Viz`
+is a step for plotting the initial and final states of the advection test for
+each resolution, mapped to the common lat-lon grid.  The colormap is controlled
+by the config options discussed in {ref}`ocean-geostrophic-config`.
+
+See {ref}`dev-visualization-global` for more details on the global lat-lon
+plots.

docs/developers_guide/ocean/tasks/index.md

@@ -7,6 +7,7 @@
 
 baroclinic_channel
 cosine_bell
+geostrophic
 inertial_gravity_wave
 manufactured_solution
 single_column

docs/users_guide/ocean/suites.md

@@ -26,7 +26,7 @@ ocean/global_convergence/qu/cosine_bell
 ```
 
 The `cosine_bell` suite runs both tasks from 
-{ref}`ocean-global-convergence-cosine-bell` in full, whereas the
+{ref}`ocean-cosine-bell` in full, whereas the
 `cosine_bell_cached_init` suite only runs the ocean simulations from as set
 of meshes and initial conditions that have been saved from a previous run
 (see {ref}`dev-cache`).

docs/users_guide/ocean/tasks/cosine_bell.md

@@ -26,6 +26,7 @@ and final state on a lat-lon grid for each resolution.  The visualization is
 not included in the `cosine_bell` version of the task in order to not slow down
 regression testing.
 
+(ocean-cosine-bell-mesh)=
 ## mesh
 
 Two global mesh variants are tested, quasi-uniform (QU) and icosohydral. Thus,
@@ -86,6 +87,7 @@ ocean/spherical/icos/cosine_bell/with_viz/base_mesh/60km
 ocean/spherical/qu/cosine_bell/with_viz/base_mesh/60km
 ```
 
+(ocean-cosine-bell-vertical)=
 ## vertical grid
 
 This task only exercises the shallow water dynamics. As such, a single
@@ -158,6 +160,7 @@ specified for a global mesh and are initialized as zeros.
 N/A. This case is run with all velocity tendencies disabled so the velocity
 field remains at the initial velocity $u_0$.
 
+(ocean-cosine-bell-time-step)=
 ## time step and run duration
 
 This task uses the Runge-Kutta 4th-order (RK4) time integrator. The time step 
@@ -181,7 +184,7 @@ 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
+# config options for convergence forward steps
 [convergence_forward]
 
 # Run duration in hours
@@ -278,6 +281,7 @@ convergence_thresh = ${cosine_bell:convergence_thresh}
 error_type = l2
 ```
 
+(ocean-cosine-bell-cores)=
 ## cores
 
 The target and minimum number of cores are determined by `goal_cells_per_core`