diff --git a/docs/developers_guide/ocean/api.rst b/docs/developers_guide/ocean/api.rst index edb7822257..39a6a2ee96 100644 --- a/docs/developers_guide/ocean/api.rst +++ b/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 diff --git a/docs/developers_guide/ocean/test_groups/tides.rst b/docs/developers_guide/ocean/test_groups/tides.rst index f5418f5384..ed41a078ad 100644 --- a/docs/developers_guide/ocean/test_groups/tides.rst +++ b/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. diff --git a/docs/users_guide/ocean/test_groups/images/M2_plot.png b/docs/users_guide/ocean/test_groups/images/M2_plot_icos7.png similarity index 100% rename from docs/users_guide/ocean/test_groups/images/M2_plot.png rename to docs/users_guide/ocean/test_groups/images/M2_plot_icos7.png diff --git a/docs/users_guide/ocean/test_groups/images/M2_plot_vr45to5.png b/docs/users_guide/ocean/test_groups/images/M2_plot_vr45to5.png new file mode 100644 index 0000000000..35c86e18ec Binary files /dev/null and b/docs/users_guide/ocean/test_groups/images/M2_plot_vr45to5.png differ diff --git a/docs/users_guide/ocean/test_groups/tides.rst b/docs/users_guide/ocean/test_groups/tides.rst index c1389b293f..247018bab5 100644 --- a/docs/users_guide/ocean/test_groups/tides.rst +++ b/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) `_ +wave drag parameterization is the default option. But MPAS-Ocean also supports +the `local generation formula `_ and +`Jayne and St.Laurent (2001) `_. 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) `_. +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