Update documentation

docs/developers_guide/ocean/api.rst

@@ -864,6 +864,14 @@ test cases and steps
    mesh.Mesh.configure
    mesh.Mesh.run
 
+   mesh.vr45to5.VRTidesMesh
+   mesh.vr45to5.VRTidesMesh.make_jigsaw_mesh
+   mesh.vr45to5.VRTidesMesh.build_cell_width_lat_lon
+   mesh.vr45to5.VRTidesMesh.limit_spacing_gradient
+   mesh.vr45to5.VRTidesMesh.swe_wavelength_spacing
+   mesh.vr45to5.VRTidesMesh.elev_sharpness_spacing
+   mesh.vr45to5.VRTidesMesh.coarsen_spacing_pixels
+
    init.Init
    init.Init.configure
    init.Init.run
@@ -872,12 +880,41 @@ test cases and steps
    init.initial_state.InitialState
    init.initial_state.InitialState.setup
    init.initial_state.InitialState.run
-   init.interpolate_wave_drag.InterpolateWaveDrag
-   init.interpolate_wave_drag.InterpolateWaveDrag.interpolate_data_to_grid
-   init.interpolate_wave_drag.InterpolateWaveDrag.plot_interp_data
-   init.interpolate_wave_drag.InterpolateWaveDrag.write_to_file
-   init.interpolate_wave_drag.InterpolateWaveDrag.run
-
+   init.calculate_wave_drag.CalculateWaveDrag
+   init.calculate_wave_drag.CalculateWaveDrag.interpolate_data_to_grid
+   init.calculate_wave_drag.CalculateWaveDrag.fix_nans
+   init.calculate_wave_drag.CalculateWaveDrag.make_nn_lists
+   init.calculate_wave_drag.CalculateWaveDrag.calc_stats
+   init.calculate_wave_drag.CalculateWaveDrag.polyfit2d
+   init.calculate_wave_drag.CalculateWaveDrag.map_to_r3
+   init.calculate_wave_drag.CalculateWaveDrag.run
+
+   dem.CreatePixelFile
+
+   dem.dem_pixel.circ_dist
+   dem.dem_pixel.cell_dzdx
+   dem.dem_pixel.blend_front
+   dem.dem_pixel.rtopo_60sec
+   dem.dem_pixel.rtopo_30sec
+   dem.dem_pixel.rtopo_15sec
+   dem.dem_pixel.gebco_60sec
+   dem.dem_pixel.gebco_30sec
+   dem.dem_pixel.gebco_15sec
+   dem.dem_pixel.rtopo_gebco_60sec
+   dem.dem_pixel.rtopo_gebco_30sec
+   dem.dem_pixel.rtopo_gebco_15sec
+
+   dem.dem_remap.map_to_r3
+   dem.dem_remap.tria_area
+   dem.dem_remap.circ_dist
+   dem.dem_remap.sample_1d
+   dem.dem_remap.linear_2d
+   dem.dem_remap.sample_2d
+   dem.dem_remap.cell_quad
+   dem.dem_remap.cell_prfl
+   dem.dem_remap.dem_remap
+
+   dem.dem_trnsf.dem_trnsf
 
    forward.Forward
    forward.Forward.configure

docs/developers_guide/ocean/test_groups/tides.rst

@@ -1,36 +1,78 @@
 .. _dev_ocean_tides:
 
 tides
-=========
+=====
 
 The ``tides`` test group implements single layer
 barotropic, tidal cases as described in :ref:`ocean_tides` in
 the User's Guide.
 
+mesh test case
+--------------
+This test case generates the bathymetric dataset and horizontal mesh for tidal simulations.
+A :py:class:`compass.ocean.tests.tides.mesh.Mesh` object is created with ``mesh_name`` as one of its
+arguments. Based on this argument, it determines the appropriate child class of 
+:py:class:`compass.mesh.spherical.SphericalBaseStep` to create the base mesh and adds a
+:py:class:`compass.ocean.mesh.cull.CullMeshStep`. Prior to creation of the base mesh, a
+:py:class:`compass.ocean.tests.tides.dem.CreatePixelFile` step is added to create the 
+"pixel" files used to remap bathymetry data onto the mesh in the initial state test case.
+
+meshes
+~~~~~~
+``tides`` currently defines 2 meshes, with more to come.
+
+Icos7
+^^^^^
+This is a uniform resolution mesh based on icosahedral subdivision. It has approximately 60 km
+resolution globally. It is defined by :py:class:`compass.mesh.spherical.IcosahedralMeshStep`.
+
+vr45to5
+^^^^^^^
+This is a variable resolution mesh which has refinement based on bathymetric depth and slope
+criteria. It has a maximum resolution of 45 km and a minimum resolution of 5 km along coastlines
+and steep bathymetric gradients. It is defined by :py:class:`compass.ocean.tests.tides.mesh.vr45to5.VRTidesMesh`
+which inherits from :py:class:`compass.mesh.spherical.QuasiUniformSphericalMeshStep` and overrides
+the ``build_cell_width_lat_lon`` method with the resolution specification previously described.
+
+
+initial state test case
+-----------------------
+This test case contains steps to calculate parameters necessary for the 
+wave drag schemes in MPAS-Ocean, remaps the bathymetry onto the mesh, and
+generates the initial state. These steps are added in the construction of 
+the :py:class:`compass.ocean.tests.tides.init.Init` object. 
+
 initial_state
--------------
+~~~~~~~~~~~~~
 The class :py:class:`compass.ocean.tests.tides.init.initial_state.InitialState`
 defines a step for running MPAS-Ocean in init mode. The vertical mesh is
 set up with a single layer. 
 
-interpolate_wave_drag
----------------------
-The class :py:class:`compass.ocean.tests.tides.init.interpolate_wave_drag.InterpolateWaveDrag`
-defines a step for interpolating HYCOM data onto the MPAS-O mesh
-for the topographic wave drag scheme.
+calculate_wave_drag
+~~~~~~~~~~~~~~~~~~~
+The class :py:class:`compass.ocean.tests.tides.init.calculate_wave_drag.CalculateWaveDrag`
+defines a step for calculating bathymetric slopes and interpolating buoyancy frequency data onto
+the MPAS-O mesh for the topographic wave drag parameterizations.
 
 remap_bathymetry
-----------------
+~~~~~~~~~~~~~~~~
 The class :py:class:`compass.ocean.tests.tides.init.remap_bathymetry.RemapBathymetry`
-defines a step to perform an integral remap of bathyetry data onto the MPAS-O mesh.
+defines a step to perform an integral remap of bathymetry data onto the MPAS-O mesh.
+
+forward test case
+-----------------
+The forward test case contains steps to run the forward simulation and 
+compare the harmonic constituents with the TPXO database. These steps
+are added in the creation of the :py:class:`compass.ocean.tests.tides.forward.Forward`
+object.
 
 forward
--------
+~~~~~~~
 The class :py:class:`compass.ocean.tests.tides.forward.forward.ForwardStep`
 defines a step to run MPAS-Ocean in forward mode.
 
 analysis
---------
+~~~~~~~~
 The class :py:class:`compass.ocean.tests.tides.analysis.Analysis`
 defines a step to extract harmonic constituent data from the TPXO database.
 These values are used to compute and plot errors.

docs/users_guide/ocean/test_groups/tides.rst

@@ -8,11 +8,15 @@ initial conditions, forward simulations, and validation for global,
 realistic ocean domains. These are single layer, barotropic simulations
 forced with tidal potential. Self-attraction and loading effects are included
 as well as a parameterization for topographic wave drag.
+Currently the `Zarron and Egbert (2006) <https://doi.org/10.1175/JPO2878.1>`_
+wave drag parameterization is the default option. But MPAS-Ocean also supports
+the `local generation formula <https://doi.org/10.5194/gmd-14-1125-2021>`_ and
+`Jayne and St.Laurent (2001) <https://doi.org/10.1029/2000GL012044>`_.
 Wetting and drying is turned on in these configurations to prevent minimum
 depth issues.
 The tidal solution is decomposed into harmonic constituents during the 
 simulation and are compared with the TPXO database.
-Currently, the icosaheral 7 mesh is supported with
+Currently, the icosaheral 7 and vr45to5 meshes are supported with
 more mesh resolutions to be added in the future.
 
 Shared config options
@@ -87,6 +91,20 @@ mesh test case
 The mesh test case produces the horizontal mesh. The base mesh has global coverage
 and is culled to remove land cells. Cells beneath ice shelves are retained in the mesh.
 
+Icos7
+^^^^^
+This mesh is an Icosahedral mesh with 7 refienemnt steps, resulting in a globally uniform
+resolution of about 60km. This mesh is meant for efficient testing of tidal physics and
+does not produce very accurate global tides (Deep RMSE M2 ~11cm).
+
+VR45to5
+^^^^^^^
+This is a variable resolution mesh that ranges between 45km to 5km
+at the coasts. It uses refiniment criteria based on depth and bathymetric slope.
+More details can be found in `Barton et al. (2022) <https://doi.org/10.1029/2022MS003207>`_.
+This mesh achieves a more accurate tidal result competitive with other non-data assimilative
+models (Deep RMSE M2 ~3.3cm).
+
 .. _tides_init:
 
 init test case
@@ -98,17 +116,21 @@ remap bathymetry step
 ^^^^^^^^^^^^^^^^^^^^^
 This step performs an integral remap of bathymetric data onto the MPAS-O mesh
 
-interpolate wave drag step
+calculate wave drag step
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
-In this step, a timescale factor from HYCOM data is interpolated onto
+In this step, a several values are calculated and interpolated onto
 the MPAS-O mesh to be used in the topographic wave drag parameterization.
-A plot is also produced to verify the interpolation.
+The climatological depth-averaged and bottom bouancy frequency values are
+interpolated from WOA are interpolated onto the MPAS mesh. The bathymetric
+gradients are also computed along with the standard deviaion of the subgrid
+bathymetry.
 
 initial state step
 ^^^^^^^^^^^^^^^^^^
 The initial state step runs MPAS-Ocean in init mode to create the initial
 condition file for the forward run. The vertical mesh is setup for a
-single layer.
+single layer. This step also computes the adjusted sea surface height,
+accounting for land ice pressure.
 
 .. _tides_forward:
 
@@ -132,6 +154,14 @@ global, shallow, and deep RMS errors. The global MPAS-O and TPXO solutions are
 plotted along with the spatial error fields. Below is an example of the type 
 of plots produced for the 5 major constituents.
 
-.. image:: images/M2_plot.png
+For the Icos7 mesh:
+
+.. image:: images/M2_plot_icos7.png
+   :width: 500px
+   :align: center
+
+And for the VR45to5 case:
+
+.. image:: images/M2_plot_vr45to5.png
    :width: 500px
    :align: center