Port drying slope test group from Compass and add new test to group

docs/developers_guide/ocean/api.md

@@ -107,6 +107,40 @@
    viz.Viz.run
 ```
 
+### drying_slope
+
+```{eval-rst}
+.. currentmodule:: polaris.ocean.tasks.drying_slope
+
+.. autosummary::
+   :toctree: generated/
+
+   add_drying_slope_tasks
+
+   baroclinic.Baroclinic
+   baroclinic.Baroclinic.configure
+
+   barotropic.Barotropic
+
+   convergence.Convergence
+   convergence.analysis.Analysis
+   convergence.analysis.Analysis.exact_solution
+   convergence.forward.Forward
+   convergence.forward.Forward.compute_cell_count
+   convergence.forward.Forward.dynamic_model_config
+
+   decomp.Decomp
+
+   init.Init
+   init.Init.run
+
+   validate.Validate
+   validate.Validate.run
+
+   viz.Viz
+   viz.Viz.run
+```
+
 ### inertial_gravity_wave 
 
 ```{eval-rst}

docs/developers_guide/ocean/tasks/drying_slope.md

@@ -0,0 +1,100 @@
+(dev-ocean-drying-slope)=
+
+# drying_slope
+
+The drying slope tests in `polaris.ocean.tasks.drying_slope` are
+variants of the drying slope test case (see {ref}`ocean-drying-slope`).
+Here, we describe the test cases and their shared framework.
+
+(dev-ocean-drying-slope-framework)=
+
+## framework
+
+The shared config options for `drying_slope` tests  are described in
+{ref}`ocean-drying-slope` in the User's Guide.
+
+Additionally, the tests share a `forward.yaml` file with a few common model
+config options related to tidal forcing and wetting and drying, as well as
+defining `mesh`, `input`, `restart`, and `output` streams.
+
+### init
+
+The class {py:class}`polaris.ocean.tasks.drying_slope.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 bathymetry is generated
+with a linearly sloping bed and ssh is set to be consistent with the initial
+tidal forcing. A vertical grid is then generated, according to the
+`vertical_grid` config options for each task.  Next, the initial
+temperature field is computed with a horizontal anomaly.
+The salinity field is uniform in the case of the `barotropic` test and has
+vertical gradients in the case of the `baroclinic` test. The initial velocity
+field is zeros.  Finally, the initial fields are plotted.
+
+The same `init` step is shared by all tasks at a given resolution.
+
+### forward
+
+The class {py:class}`polaris.ocean.tasks.drying_slope.forward.Forward`
+defines a step for running MPAS-Ocean from the initial condition produced in
+the `init` step.  The time integration scheme, drag options, and tidal forcing
+are set here. Namelist and streams files are updated in
+{py:meth}`polaris.ocean.tasks.drying_slope.forward.Forward.dynamic_model_config()`
+with time steps determined algorithmically based on config options.  The
+number of cells is approximated from config options in
+{py:meth}`polaris.ocean.tasks.drying_slope.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.
+
+### validate
+
+The class {py:class}`polaris.ocean.tasks.drying_slope.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.
+
+### viz
+
+The class {py:class}`polaris.ocean.tasks.drying_slope.viz.Viz`
+defines a step for visualizing horizontal fields and transects from the
+forward step as well as the ssh forcing and reference solutions.
+
+(dev-ocean-drying-slope-baroclinic)=
+
+## baroclinic
+
+The {py:class}`polaris.ocean.tasks.drying_slope.baroclinic.Baroclinic`
+test runs a drying test at a linear tidal forcing rate with vertical
+stratification.
+
+(dev-ocean-drying-slope-barotropic)=
+
+## barotropic
+
+The {py:class}`polaris.ocean.tasks.drying_slope.barotropic.Barotropic`
+test runs one sinusoidal cycle of tidal forcing.
+
+(dev-ocean-drying-slope-decomp)=
+
+## decomp
+
+The {py:class}`polaris.ocean.tasks.drying_slope.decomp.Decomp`
+performs a 3-time-step run once on 4 cores and once on 8 cores. The
+`validate` step ensures that the two runs produce identical results.
+
+(dev-ocean-drying-slope-convergence)=
+
+## convergence
+
+The {py:class}`polaris.ocean.tasks.drying_slope.convergence.Convergence`
+tests the convergence of the barotropic test with resolution and time step
+against a reference solution.
+
+The `analysis` step defined by
+{py:class}`polaris.ocean.tasks.drying_slope.convergence.analysis.Analysis`
+produces a figure of the RMSE as a function of resolution.

docs/developers_guide/ocean/tasks/index.md

@@ -8,6 +8,7 @@
 baroclinic_channel
 correlated_tracers_2d
 cosine_bell
+drying_slope
 geostrophic
 divergent_2d
 inertial_gravity_wave

docs/users_guide/ocean/tasks/drying_slope.md

@@ -0,0 +1,241 @@
+(ocean-drying-slope)=
+
+# drying slope
+
+The drying_slope tasks test wetting-and-drying algorithms in domains designed
+to represent a coastline with sloping bathymetry.
+
+## config options
+
+There are a number of config options that are common to all drying_slope tasks:
+
+```cfg
+# config options for all drying slope test cases
+[drying_slope]
+
+# time integration scheme
+time_integrator = RK4
+
+# time step per resolution (s/km), since dt is proportional to resolution
+rk4_dt_per_km = 30
+
+split_dt_per_km = 30
+
+# barotropic time step per resolution (s/km), since btr_dt is proportional to
+# resolution
+btr_dt_per_km = 1.5
+
+# Coriolis parameter
+coriolis_parameter = 0.0
+```
+
+(ocean-drying-slope-baroclinic)=
+
+## baroclinic
+
+The baroclinic drying_slope task is designed to test wetting-and-drying
+algorithms in a multi-layer configuration with vertial gradients in scalars.
+
+### description
+
+Description of the test case.
+
+```{image} images/drying_slope_baroclinic.png
+:align: center
+:width: 500 px
+```
+
+### mesh
+
+Specify whether the mesh is global or planar and the resolution(s) tested. If
+planar, specify the mesh size. If global, specify whether the mesh is
+icosohedral or quasi-uniform. Specify any relevant options in the config file
+pertaining to setting up the mesh.
+
+### vertical grid
+
+If there are no restrictions on the vertical grid specifications inherent to
+the test case, then the config section may be provided without any further
+description.
+
+Examples of restrictions or special conditions warranting description may
+include:
+
+* Whether the topography is variable
+* Whether the test pertains to shallow water dynamics, in which case the
+minimum number of vertical levels may be used
+* Whether there are several test cases in the test group investigating the
+effects of different vertical coordinates (`coord_type`)
+
+The minimum layer thickness for this case is determined by the minimum column thickness
+from the config option `drying_slope_baroclinic:min_column_thickness`.
+
+```cfg
+# Options related to the vertical grid
+[vertical_grid]
+
+# the type of vertical grid
+grid_type = uniform
+
+# The type of vertical coordinate (e.g. z-level, z-star)
+coord_type = sigma
+
+# Number of vertical levels
+vert_levels = 10
+
+# 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
+
+# The minimum number of vertical levels for multi-layer cases
+min_vert_levels = 3
+
+# Minimum thickness of each layer
+min_layer_thickness = ${drying_slope_barotropic:thin_film_thickness}
+```
+
+### initial conditions
+
+The initial conditions should be specified for all variables requiring
+initial conditions (see {ref}`dev-ocean-models`).
+
+### forcing
+
+If applicable, specify the forcing applied at each time step of the simulation
+(in MPAS-Ocean, these are the variables contained in the `forcing` stream).
+If not applicable, keep this section with the notation N/A.
+
+### time step and run duration
+
+The time step for forward integration should be specified here for the test
+case's resolution. The run duration should also be specified.
+
+### config options
+
+The config options define the geometry of the domain.
+
+```cfg
+# config options for barotropic drying slope test cases
+[drying_slope_baroclinic]
+
+# the width of the domain in km
+lx = 12.
+
+# the length of the domain in km
+ly = 55.
+
+# Length over which wetting and drying actually occur in km
+ly_analysis = 50.
+
+# Bottom depth at the right side of the domain in m
+right_bottom_depth = 2.5
+
+# Bottom depth at the left side of the domain in m
+left_bottom_depth = 0.
+
+# Initial SSH at the right side of the domain in m
+right_tidal_height = 0.
+
+# salinity at the right side of the domain
+right_salinity = 35.0
+
+# salinity at the left side of the domain
+left_salinity = 1.0
+
+# manning coefficient used in mannings bottom drag type
+manning_coefficient = 5.0e-2
+
+# The column thickness in the thin film region, used to determine thin film
+# thickness
+min_column_thickness = 0.05
+```
+
+Include here any further description of each of the config options.
+
+### cores
+
+Specify whether the number of cores is determined by `goal_cells_per_core` and
+`max_cells_per_core` in the `ocean` section of the config file or whether the
+default and minimum number of cores is given in arguments to the forward step,
+and what those defaults are.
+
+## barotropic
+
+### description
+
+Description of the test case.
+
+```{image} images/drying_slope_barotropic.png
+:align: center
+:width: 500 px
+```
+### vertical grid
+
+The vertical grid is the same as baroclinic except a single layer may be used and
+the minimum layer thickness given in `drying_slope_barotropic:thin_film_thickness`
+is used.
+
+### config options
+
+The config options define the geometry of the domain.
+
+```cfg
+# config options for barotropic drying slope test cases
+[drying_slope_barotropic]
+
+# the width of the domain in km
+lx = 6.
+
+# Length over which wetting and drying actually occur in km
+ly_analysis = 25.
+
+# the length of the domain in km
+ly = 28.
+
+# Bottom depth at the right side of the domain in m
+right_bottom_depth = -10.
+
+# Bottom depth at the left side of the domain in m
+left_bottom_depth = 0.
+
+# Initial SSH at the right side of the domain in m
+right_tidal_height = ${drying_slope_barotropic:right_bottom_depth}
+
+# Plug width as a fraction of the domain
+plug_width_frac = 0.0
+
+# Plug temperature
+plug_temperature = 20.0
+
+# Background temperature
+background_temperature = 20.0
+
+# Background salinity
+background_salinity = 35.0
+
+# Thickness of each layer in the thin film region
+thin_film_thickness = 1.0e-3
+```
+
+## convergence
+
+### description
+
+```{image} images/drying_slope_convergence.png
+:align: center
+:width: 500 px
+```
+### config options
+
+The config options define the resolutions to use in the convergence test:
+
+```cfg
+# config options for drying slope convergence task
+[drying_slope_convergence]
+
+# horizontal resolutions in km
+resolutions = 0.25, 0.5, 1, 2
+```
+

docs/users_guide/ocean/tasks/index.md

@@ -8,6 +8,7 @@
 baroclinic_channel
 correlated_tracers_2d
 cosine_bell
+drying_slope
 geostrophic
 divergent_2d
 inertial_gravity_wave