Merge pull request #158 from cbegeman/ocn-port-ice-shelf-2d

Port ice_shelf_2d test cases

Author: xylar

docs/developers_guide/ocean/api.md

@@ -107,6 +107,32 @@
    viz.Viz.run
 ```
 
+### ice_shelf_2d
+
+```{eval-rst}
+.. currentmodule:: polaris.ocean.tasks.ice_shelf_2d
+
+.. autosummary::
+   :toctree: generated/
+
+   add_ice_shelf_2d_tasks
+
+   default.Default
+
+   forward.Forward
+   forward.Forward.compute_cell_count
+   forward.Forward.dynamic_model_config
+
+   init.Init
+   init.Init.run
+
+   validate.Validate
+   validate.Validate.run
+   
+   viz.Viz
+   viz.Viz.run
+```
+
 ### inertial_gravity_wave 
 
 ```{eval-rst}
@@ -283,6 +309,25 @@
    SphericalConvergenceForward.compute_cell_count
 ```
 
+### Ice Shelf
+
+```{eval-rst}
+.. currentmodule:: polaris.ocean.ice_shelf
+
+.. autosummary::
+   :toctree: generated/
+
+   IceShelfTask
+   IceShelfTask.setup_ssh_adjustment_steps
+
+   SshAdjustment
+   SshAdjustment.run
+
+   SshForward
+   SshForward.compute_cell_count
+   SshForward.dynamic_model_config
+```
+
 ### Ocean Model
 
 ```{eval-rst}
@@ -336,11 +381,16 @@
    vertical.grid_1d.write_1d_grid
    vertical.partial_cells.alter_bottom_depth
    vertical.partial_cells.alter_ssh
+   vertical.sigma.init_sigma_vertical_coord
+   vertical.sigma.update_sigma_layer_thickness
+   vertical.update_layer_thickness
    vertical.zlevel.init_z_level_vertical_coord
+   vertical.zlevel.update_z_level_layer_thickness
    vertical.zlevel.compute_min_max_level_cell
    vertical.zlevel.compute_z_level_layer_thickness
    vertical.zlevel.compute_z_level_resting_thickness
    vertical.zstar.init_z_star_vertical_coord
+   vertical.zstar.update_z_star_layer_thickness
 ```
 
 ### Visualization

docs/developers_guide/ocean/framework.md

@@ -383,6 +383,25 @@ rather needs to be computed.  The default behavior is to read the requested
 variable (the value associate the `'name'` key) at the time index closest to
 the evaluation time specified by the `convergence_eval_time` config option.
 
+(dev-ocean-framework-ice-shelf)=
+
+## Ice Shelf Tasks
+
+The `polaris.ocean.ice_shelf` module provides support for ice shelf tasks.
+
+The {py:class}`polaris.ocean.ice_shelf.IceShelf` class can serve as a parent
+class for ice shelf tests, such as
+{py:class}`polaris.ocean.tasks.ice_shelf_2d.IceShelf2d`.
+
+The {py:meth}`polaris.ocean.ice_shelf.IceShelf.setup_ssh_adjustment_steps()`
+sets up `ssh_forward` and `ssh_adjustment` steps from the classes
+{py:class}`polaris.ocean.ice_shelf.ssh_forward.SshForward`
+{py:class}`polaris.ocean.ice_shelf.ssh_adjustment.SshAdjustment`.
+The `ssh_adjustment` section of the config file sets the parameters for these
+steps, as described in {ref}`ocean-ssh-adjustment`. It returns the last
+`ssh_adjustment` step, which is typically used as the
+initial state for subsequent forward steps.
+
 (dev-ocean-framework-vertical)=
 
 ## Vertical coordinate
@@ -402,7 +421,10 @@ this section of the config file. The function
 `minLevelCell`, `maxLevelCell`, `cellMask`, `layerThickness`, `zMid`,
 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`.
+as config options from `vertical_grid`. The function
+{py:func}`polaris.ocean.vertical.update_layer_thickness` can be used to update
+`layerThickness` when either or both of `bottomDepth` and `ssh` have been
+changed.
 
 (dev-ocean-rpe)=
 

docs/developers_guide/ocean/tasks/correlated_tracers_2d.md

@@ -13,14 +13,14 @@ of convergence.
 ## framework
 
 The config options for the `correlated_tracers_2d` test is described in 
-{ref}`ocean-correlated_tracers-2d` in the User's Guide.
+{ref}`ocean-correlated-tracers-2d` 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.  This file has Jinja templating that is
 used to update model config options based on Polaris config options, see
-{ref}`dev-ocean-spherical-convergence`.
+{ref}`dev-ocean-convergence`.
 
 ### base_mesh
 

docs/developers_guide/ocean/tasks/divergent_2d.md

@@ -20,7 +20,7 @@ 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.  This file has Jinja templating that is
 used to update model config options based on Polaris config options, see
-{ref}`dev-ocean-spherical-convergence`.
+{ref}`dev-ocean-convergence`.
 
 ### base_mesh
 

docs/developers_guide/ocean/tasks/geostrophic.md

@@ -35,7 +35,7 @@ in {ref}`ocean-geostrophic-init` in the User's Guide.
 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
+an `init` step. See {ref}`dev-ocean-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`.

docs/developers_guide/ocean/tasks/ice_shelf_2d.md

@@ -0,0 +1,88 @@
+(dev-ocean-ice-shelf-2d)=
+
+# ice_shelf_2d
+
+The `ice_shelf_2d` test group
+(`polaris.ocean.tasks.ice_shelf_2d.IceShelf2d`)
+implements a very simplified ice-shelf cavity that is invariant in the x
+direction (see {ref}`ocean-ice-shelf-2d`). Here, we describe the shared
+framework for this test group and the 2 test cases.
+
+(dev-ocean-ice-shelf-2d-framework)=
+
+## framework
+
+The shared config options for the `ice_shelf_2d` test group
+are described in {ref}`ocean-ice-shelf-2d` in the User's Guide.
+
+Additionally, the test group has shared `ssh_forward.yaml` and `forward.yaml`
+files with common namelist options and streams related to the `ssh_adjustment`
+and `forward` steps, respectively.
+
+The test case class is inherited from
+{py:class}`polaris.ocean.ice_shelf.IceShelfTask` and
+its {py:class}`polaris.ocean.ice_shelf.ssh_forward.SshForward` and
+{py:class}`polaris.ocean.ice_shelf.ssh_adjustment.SshAdjustment` step classes
+are used to set up one of each step for each iteration given by the config
+option `ssh_adjustment:iterations`.
+
+### init
+
+The class :py:class:`polaris.ocean.tasks.ice_shelf_2d.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.  A vertical grid is generated,
+with 20 layers of 100-m thickness each by default.  Then, the 1D grid is either
+"squashed" down so the sea-surface height corresponds to the location of the
+ice-ocean interface (ice draft) using a z-star {ref}`dev-ocean-framework-vertical`
+or top layers are removed where there is an ice shelf using a z-level
+coordinate. Finally, the initial salinity profile is computed along with
+uniform temperature and zero initial velocity.
+
+### forward
+
+The class {py:class}`compass.ocean.tests.ice_shelf_2d.forward.Forward`
+defines a step for running MPAS-Ocean from the initial condition produced in
+the `init` step. 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. 
+
+### validate
+
+The class {py:class}`polaris.ocean.tasks.ice_shelf_2d.validate.Validate`
+defines a step for validating outputs in two step directories against one
+another.  This step ensures that `temperature`, `salinity`, `layerThickness` 
+and `normalVelocity` are identical in `output.nc` files in the two steps.
+It also checks a number of land ice variables and frazil variables stored in
+`land_ice_fluxes.nc` and `frazil.nc`, respectively. This step is used by the
+restart test (see {ref}`dev-ocean-ice-shelf-2d-restart`).
+
+### viz
+
+The class {py:class}`polaris.ocean.tasks.ice_shelf_2d.viz.Viz` uses the planar
+visualization capabilities provided by
+{py:func}`polaris.ocean.viz.compute_transect()`.
+
+(dev-ocean-ice-shelf-2d-default)=
+
+## default
+
+The {py:class}`polaris.ocean.tasks.ice_shelf_2d.default.Default` test case
+config options are described in {ref}`ocean-ice-shelf-2d-default`.
+
+The test creates and mesh and initial condition, performs 15 iterations of
+SSH adjustment to make sure the SSH is as close as possible to being in
+dynamic balance with the land-ice pressure.  Then, it performs a 10-minute
+ forward simulation. If a baseline is provided, a large number of variables
+(both prognostic and related to land-ice fluxes) are checked to make sure
+they match the baseline.
+
+The restart test, `ocean/planar/ice_shelf_2d/$RES/$COORD_TYPE/default/with_restart`
+is just a variant of the default test that has two additional steps, a `forward`
+step and a `validate` step. 
+
+The tidal forcing test, `ocean/planar/ice_shelf_2d/$RES/$COORD_TYPE/default_tidal_forcing`
+is a variant of the `default` test that has tidal forcing, is run for longer
+(0.1 days), and uses the RK4 time integration scheme by default.

docs/developers_guide/ocean/tasks/index.md

@@ -10,6 +10,7 @@ correlated_tracers_2d
 cosine_bell
 geostrophic
 divergent_2d
+ice_shelf_2d
 inertial_gravity_wave
 internal_wave
 manufactured_solution

docs/developers_guide/ocean/tasks/nondivergent_2d.md

@@ -20,7 +20,7 @@ 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.  This file has Jinja templating that is
 used to update model config options based on Polaris config options, see
-{ref}`dev-ocean-spherical-convergence`.
+{ref}`dev-ocean-convergence`.
 
 ### base_mesh
 

docs/developers_guide/ocean/tasks/rotation_2d.md

@@ -20,7 +20,7 @@ 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.  This file has Jinja templating that is
 used to update model config options based on Polaris config options, see
-{ref}`dev-ocean-spherical-convergence`.
+{ref}`dev-ocean-convergence`.
 
 ### base_mesh
 

docs/users_guide/ocean/framework/ice_shelf.md

@@ -0,0 +1,55 @@
+(ocean-ice-shelf)=
+
+# Ice shelf
+
+The framework defines an `IceShelfTask` class that provides methods common
+to tasks that feature ice shelf cavities. At present, the only method included
+sets up ssh adjustment steps, described in ocean-ssh-adjustment.
+
+(ocean-ssh-adjustment)=
+
+## SSH adjustment steps
+
+For tasks that feature ice shelf cavities, a series of forward simulations is
+run in order to iteratively bring the SSH in equilibrium with the land ice
+pressure. These steps are typically shared between all tasksthat also share
+initial conditions and namelist options that influence the dynamics. Only the
+output from the final SSH adjustment step is used as the initial state for the
+forward step(s) of the task.
+
+### config options
+
+The following config options are used by SSH adjustment steps. The defaults are
+shown here, but may be changed in a task's local config file.
+
+```cfg
+# Options related to ssh adjustment steps
+[ssh_adjustment]
+
+# Number of ssh adjustment iterations
+iterations = 10
+
+# Output interval for the ssh adjustment phase in hours
+output_interval = 1.0
+
+# Run duration of each ssh adjustment phase in hours
+run_duration = 1.0
+
+# Variable in init.nc that determines where to adjust SSH
+mask_variable = adjustSSHMask
+
+# Whether to adjust land ice pressure or SSH
+adjust_variable = landIcePressure
+
+# Time integration scheme
+time_integrator = split_explicit
+
+# Time step in seconds as a function of resolution
+rk4_dt_per_km = 6
+
+# Time step in seconds as a function of resolution
+split_dt_per_km = 6
+
+# Time step in seconds as a function of resolution
+btr_dt_per_km = 1
+```

docs/users_guide/ocean/framework/index.md

@@ -9,4 +9,5 @@ across tasks.
 :titlesonly: true
 
 vertical
+ice_shelf
 ```