Working on documentation links

docs/parameterizations_lateral.rst

@@ -8,6 +8,8 @@ Lateral viscosity
 
 Laplacian and bi-harmonic viscosities with linear and Smagorinsky options are implemented in MOM_hor_visc.
 
+    :ref:`namespacemom__hor__visc_1section_horizontal_viscosity`
+
 Gent-McWilliams/TEM/isopycnal height diffusion
 ----------------------------------------------
 
@@ -20,7 +22,7 @@ scaling.
 A model of sub-grid scale Mesoscale Eddy Kinetic Energy (MEKE) is implement in MOM_MEKE and the associated diffusivity added in MOM_thickness_diffuse.
 See :cite:`jansen2015` and :cite:`marshall2010`.
 
-   :ref:`namespacemom__meke_1section_MEKE`
+    :ref:`namespacemom__meke_1section_MEKE`
 
 Backscatter
 -----------
@@ -37,15 +39,38 @@ which now also contains the mixed layer restratication comes from :cite: Bodner2
 
     :ref:`namespacemom__mixed__layer__restrat_1section_mle`
 
+Interface filtering
+-------------------
+
+For layer mode, one can filter the interface thicknesses:
+
+    :ref:`namespacemom__interface__filter_1section_interface_filter`
+
 Lateral diffusion
 -----------------
 
 See :ref:`Horizontal_Diffusion`.
 
+See also :ref:`namespacemom__lateral__mixing__coeffs_1section_Resolution_Function`
+
 Tidal forcing
 -------------
 
 Astronomical tidal forcings and self-attraction and loading are implement in MOM_tidal_forcing.
 Tides can also be added via an open boundary tidal specification,
-see [OBC wiki page](https://github.com/NOAA-GFDL/MOM6-examples/wiki/Open-Boundary-Conditions).
+see `OBC wiki page <https://github.com/NOAA-GFDL/MOM6-examples/wiki/Open-Boundary-Conditions>`_.
+
+The Love numbers are stored internally in MOM_load_love_numbers:
+
+    :ref:`namespacemom__load__love__numbers_1section_Love_numbers`
+
+While the self attraction and loading is computed in MOM_self_attr_load:
+
+    :ref:`namespaceself__attr__load_1section_SAL`
+
+Spherical Harmonics
+-------------------
+
+The model needs spherical, computed in MOM_spherical_harmonics:
 
+    :ref:`namespacemom__spherical__harmonics_1section_spherical_harmonics`

docs/zotero.bib

@@ -2524,7 +2524,7 @@ @article{visbeck1997
 }
 
 @article{visbeck1996,
-	author = {Viscbeck, M. and J.C. Marshall and H. Jones},
+	author = {Visbeck, M. and J.C. Marshall and H. Jones},
 	year = {1996},
 	title = {Dynamics of isolated convective regions in the ocean},
 	journal = {J. Phys. Oceanogr.},
@@ -2801,3 +2801,160 @@ @article{Oberhuber1993
 	pages={808–829}
 }
 
+@article{Smith2003,
+	title={Anisotropic horizontal viscosity for ocean models},
+	volume={5},
+	ISSN={1463-5003},
+	url={http://dx.doi.org/10.1016/s1463-5003(02)00016-1},
+	DOI={10.1016/s1463-5003(02)00016-1},
+	number={2},
+	journal={Ocean Modelling},
+	publisher={Elsevier BV},
+	author={Smith, Richard D. and McWilliams, James C.},
+	year={2003},
+	month=jan,
+	pages={129–156}
+}
+
+@article{Large2001,
+	title={Equatorial Circulation of a Global Ocean Climate Model with Anisotropic Horizontal Viscosity},
+	volume={31},
+	ISSN={1520-0485},
+	url={http://dx.doi.org/10.1175/1520-0485(2001)031<0518:ECOAGO>2.0.CO;2},
+	DOI={10.1175/1520-0485(2001)031<0518:ecoago>2.0.co;2},
+	number={2},
+	journal={Journal of Physical Oceanography},
+	publisher={American Meteorological Society},
+	author={Large, William G. and Danabasoglu, Gokhan and McWilliams, James C. and Gent, Peter R. and Bryan, Frank O.},
+	year={2001},
+	month=feb,
+	pages={518–536}
+}
+
+@inproceedings{Smagorinsky1993,
+	author={Joseph Smagorinsky},
+	year={1993},
+	title={Some historical remarks on the use of non-linear viscosities},
+	booktitle={Large Eddy Simulation of Complex Engineering and Geophysical Flows},
+	note={Proceedings of an International Workshop in Large Eddy Simulation},
+	address={Cambridge, UK},
+	publisher={Cambridge University Press},
+	pages={1--34}
+}
+
+@article{Barton2022,
+	title={Global Barotropic Tide Modeling Using Inline Self‐Attraction and Loading in MPAS‐Ocean},
+	volume={14},
+	ISSN={1942-2466},
+	url={http://dx.doi.org/10.1029/2022MS003207},
+	DOI={10.1029/2022ms003207},
+	number={11},
+	journal={Journal of Advances in Modeling Earth Systems},
+	publisher={American Geophysical Union (AGU)},
+	author={Barton, Kristin N. and Pal, Nairita and Brus, Steven R. and Petersen, Mark R. and Arbic, Brian K. and Engwirda, Darren and Roberts, Andrew F. and Westerink, Joannes J. and Wirasaet, Damrongsak and Schindelegger, Michael},
+	year={2022},
+	month=nov
+}
+
+@article{Brus2023,
+	title={Scalable self attraction and loading calculations for unstructured ocean tide models},
+	volume={182},
+	ISSN={1463-5003},
+	url={http://dx.doi.org/10.1016/j.ocemod.2023.102160},
+	DOI={10.1016/j.ocemod.2023.102160},
+	journal={Ocean Modelling},
+	publisher={Elsevier BV},
+	author={Brus, Steven R. and Barton, Kristin N. and Pal, Nairita and Roberts, Andrew F. and Engwirda, Darren and Petersen, Mark R. and Arbic, Brian K. and Wirasaet, Damrongsak and Westerink, Joannes J. and Schindelegger, Michael},
+	year={2023},
+	month=apr,
+	pages={102160}
+}
+
+@article{Blewitt2003,
+	title={Self‐consistency in reference frames, geocenter definition, and surface loading of the solid Earth},
+	volume={108},
+	ISSN={0148-0227},
+	url={http://dx.doi.org/10.1029/2002JB002082},
+	DOI={10.1029/2002jb002082},
+	number={B2},
+	journal={Journal of Geophysical Research: Solid Earth},
+	publisher={American Geophysical Union (AGU)},
+	author={Blewitt, Geoffrey},
+	year={2003},
+	month=feb
+}
+
+@article{Wang2012,
+	author={Wang, H., Xiang, L., Jia, L., Jiang, L., Wang, Z., Hu, B. and Gao, P.},
+	year={2012},
+	title={Load Love numbers and Green's functions
+for elastic Earth models PREM, iasp91, ak135, and modified models with refined crustal structure from Crust 2.0},
+	journal={Computers & Geosciences},
+	volume={49},
+	pages={190--199}
+}
+
+@article{Jansen2015,
+	title={Parameterization of eddy fluxes based on a mesoscale energy budget},
+	volume={92},
+	ISSN={1463-5003},
+	url={http://dx.doi.org/10.1016/j.ocemod.2015.05.007},
+	DOI={10.1016/j.ocemod.2015.05.007},
+	journal={Ocean Modelling},
+	publisher={Elsevier BV},
+	author={Jansen, Malte F. and Adcroft, Alistair J. and Hallberg, Robert and Held, Isaac M.},
+	year={2015},
+	month=aug,
+	pages={28–-41}
+}
+
+@inproceedings{Hallberg2003,
+	title={The ability of large-scale ocean models to accept parameterizations of boundary mixing, and a description of a refined bulk mixed-layer model},
+	author={Robert Hallberg},
+	year={2003},
+	booktitle={Internal Gravity Waves and Small-Scale Turbulence: Proc.‘Aha Huliko ‘a Hawaiian Winter Workshop},
+	pages={187--203}
+}
+
+@article{1978,
+	volume={290},
+	ISSN={2054-0272},
+	url={http://dx.doi.org/10.1098/rsta.1978.0083},
+	DOI={10.1098/rsta.1978.0083},
+	number={1368},
+	journal={Philosophical Transactions of the Royal Society of London. Series A, Mathematical and Physical Sciences},
+	publisher={The Royal Society},
+	year={1978},
+	month=nov,
+	pages={235-–266}
+}
+
+@article{Arbic2004,
+	title={The accuracy of surface elevations in forward global barotropic and baroclinic tide models},
+	volume={51},
+	ISSN={0967-0645},
+	url={http://dx.doi.org/10.1016/j.dsr2.2004.09.014},
+	DOI={10.1016/j.dsr2.2004.09.014},
+	number={25–26},
+	journal={Deep Sea Research Part II: Topical Studies in Oceanography},
+	publisher={Elsevier BV},
+	author={Arbic, Brian K. and Garner, Stephen T. and Hallberg, Robert W. and Simmons, Harper L.},
+	year={2004},
+	month=dec,
+	pages={3069-–3101}
+}
+
+@article{Schaeffer2013,
+	title={Efficient spherical harmonic transforms aimed at pseudospectral numerical simulations},
+	volume={14},
+	ISSN={1525-2027},
+	url={http://dx.doi.org/10.1002/ggge.20071},
+	DOI={10.1002/ggge.20071},
+	number={3},
+	journal={Geochemistry, Geophysics, Geosystems},
+	publisher={American Geophysical Union (AGU)},
+	author={Schaeffer, Nathanaël},
+	year={2013},
+	month=mar,
+	pages={751-–758}
+}

src/parameterizations/lateral/MOM_hor_visc.F90

@@ -3193,25 +3193,25 @@ subroutine hor_visc_end(CS)
 end subroutine hor_visc_end
 !> \namespace mom_hor_visc
 !!
+!! \section section_horizontal_viscosity Horizontal viscosity in MOM
+!!
 !! This module contains the subroutine horizontal_viscosity() that calculates the
 !! effects of horizontal viscosity, including parameterizations of the value of
 !! the viscosity itself. horizontal_viscosity() calculates the acceleration due to
 !! some combination of a biharmonic viscosity and a Laplacian viscosity. Either or
 !! both may use a coefficient that depends on the shear and strain of the flow.
 !! All metric terms are retained. The Laplacian is calculated as the divergence of
-!! a stress tensor, using the form suggested by Smagorinsky (1993). The biharmonic
+!! a stress tensor, using the form suggested by \cite Smagorinsky1993. The biharmonic
 !! is calculated by twice applying the divergence of the stress tensor that is
 !! used to calculate the Laplacian, but without the dependence on thickness in the
 !! first pass. This form permits a variable viscosity, and indicates no
 !! acceleration for either resting fluid or solid body rotation.
 !!
-!! The form of the viscous accelerations is discussed extensively in Griffies and
-!! Hallberg (2000), and the implementation here follows that discussion closely.
-!! We use the notation of Smith and McWilliams (2003) with the exception that the
+!! The form of the viscous accelerations is discussed extensively in \cite griffies2000,
+!! and the implementation here follows that discussion closely.
+!! We use the notation of \cite Smith2003 with the exception that the
 !! isotropic viscosity is \f$\kappa_h\f$.
 !!
-!! \section section_horizontal_viscosity Horizontal viscosity in MOM
-!!
 !! In general, the horizontal stress tensor can be written as
 !! \f[
 !! {\bf \sigma} =
@@ -3357,7 +3357,7 @@ end subroutine hor_visc_end
 !!
 !! \subsection section_anisotropic_viscosity Anisotropic viscosity
 !!
-!! Large et al., 2001, proposed enhancing viscosity in a particular direction and the
+!! \cite Large2001, proposed enhancing viscosity in a particular direction and the
 !! approach was generalized in Smith and McWilliams, 2003. We use the second form of their
 !! two coefficient anisotropic viscosity (section 4.3). We also replace their
 !! \f$A^\prime\f$ and $D$ such that \f$2A^\prime = 2 \kappa_h + D\f$ and

src/parameterizations/lateral/MOM_lateral_mixing_coeffs.F90

@@ -1728,7 +1728,7 @@ end subroutine VarMix_end
 !! \f]
 !!
 !! \todo Check this reference to Bob on/off paper.
-!! The resolution function used in scaling diffusivities (Hallberg, 2010) is
+!! The resolution function used in scaling diffusivities (\cite hallberg2013) is
 !!
 !! \f[
 !! r(\Delta,L_d) = \frac{1}{1+(\alpha R)^p}

src/parameterizations/lateral/MOM_load_love_numbers.F90

@@ -1452,15 +1452,17 @@ module MOM_load_love_numbers
             /), (/4, lmax+1/)) !< Load Love numbers
 
 !> \namespace mom_load_love_numbers
+!! \section section_Love_numbers The Love numbers
+!!
 !! This module serves the sole purpose of storing load Love number. The Love numbers are used for the spherical harmonic
 !! self-attraction and loading (SAL) calculation in MOM_self_attr_load module. This separate module ensures readability
 !! of the SAL module.
 !!
 !! Variable Love_Data stores the Love numbers up to degree 1440. From left to right: degree, h, l, and k. Data in this
 !! module is imported from SAL calculation in Model for Prediction Across Scales (MPAS)-Ocean developed by Los Alamos
-!! National Laboratory and University of Michigan [Barton et al. (2022) and Brus et al. (2022)]. The load Love numbers
-!! are from Wang et al. (2012), which are in the center of mass of total Earth system reference frame (CM). When used,
-!! Love numbers with degree<2 should be converted to center of mass solid Earth reference frame (CF) [Blewitt (2003)],
+!! National Laboratory and University of Michigan [\cite Barton2022 and \cite Brus2022]. The load Love numbers
+!! are from \cite Wang2012, which are in the center of mass of total Earth system reference frame (CM). When used,
+!! Love numbers with degree<2 should be converted to center of mass solid Earth reference frame (CF) [\cite Blewitt2003],
 !! as in subroutine calc_love_scaling in MOM_tidal_forcing module.
 !!
 !! References:
@@ -1483,4 +1485,4 @@ module MOM_load_love_numbers
 !! for elastic Earth models PREM, iasp91, ak135, and modified models with refined crustal structure from Crust 2.0.
 !! Computers & Geosciences, 49, pp.190-199.
 !! https://doi.org/10.1016/j.cageo.2012.06.022
-end module MOM_load_love_numbers
+end module MOM_load_love_numbers

src/parameterizations/lateral/MOM_mixed_layer_restrat.F90

@@ -1704,7 +1704,7 @@ logical function mixedlayer_restrat_init(Time, G, GV, US, param_file, diag, CS,
              "mesoscale eddy kinetic energy to the large-scale "//&
              "geostrophic kinetic energy or 1 plus the square of the "//&
              "grid spacing over the deformation radius, as detailed "//&
-             "by Fox-Kemper et al. (2010)", units="nondim", default=0.0)
+             "by Fox-Kemper et al. (2011)", units="nondim", default=0.0)
     ! These parameters are only used in the OM4-era version of Fox-Kemper
     call get_param(param_file, mdl, "USE_STANLEY_ML", CS%use_Stanley_ML, &
                    "If true, turn on Stanley SGS T variance parameterization "// &
@@ -1750,7 +1750,7 @@ logical function mixedlayer_restrat_init(Time, G, GV, US, param_file, diag, CS,
         call get_param(param_file, mdl, "MLE_DENSITY_DIFF", CS%MLE_density_diff, &
              "Density difference used to detect the mixed-layer "//&
              "depth used for the mixed-layer eddy parameterization "//&
-             "by Fox-Kemper et al. (2010)", units="kg/m3", default=0.03, scale=US%kg_m3_to_R)
+             "by Fox-Kemper et al. (2011)", units="kg/m3", default=0.03, scale=US%kg_m3_to_R)
       endif
       call get_param(param_file, mdl, "MLE_TAIL_DH", CS%MLE_tail_dh, &
              "Fraction by which to extend the mixed-layer restratification "//&
@@ -1965,14 +1965,14 @@ end function test_answer
 !! \section section_mle Mixed-layer eddy parameterization module
 !!
 !! The subroutines in this module implement a parameterization of unresolved viscous
-!! mixed layer restratification of the mixed layer as described in Fox-Kemper et
-!! al., 2008, and whose impacts are described in Fox-Kemper et al., 2011.
+!! mixed layer restratification of the mixed layer as described in \cite fox-kemper2008,
+!! and whose impacts are described in \cite fox-kemper2011.
 !! This is derived in part from the older parameterization that is described in
-!! Hallberg (Aha Hulikoa, 2003), which this new parameterization surpasses, which
-!! in turn is based on the sub-inertial mixed layer theory of Young (JPO, 1994).
+!! \cite Hallberg2003, which this new parameterization surpasses, which
+!! in turn is based on the sub-inertial mixed layer theory of \cite Young1994.
 !! There is no net horizontal volume transport due to this parameterization, and
 !! no direct effect below the mixed layer. A revised of the parameterization by
-!! Bodner et al., 2023, is also available as an option.
+!! \cite Bodner2023, is also available as an option.
 !!
 !! This parameterization sets the restratification timescale to agree with
 !! high-resolution studies of mixed layer restratification.
@@ -1986,8 +1986,8 @@ end function test_answer
 !!
 !! The parameterization is colloquially referred to as "sub-meso".
 !!
-!! The original Fox-Kemper et al., (2008b) paper proposed a quasi-Stokes
-!! advection described by the stream function (eq. 5 of Fox-Kemper et al., 2011):
+!! The original \cite fox-kemper2008-2 paper proposed a quasi-Stokes
+!! advection described by the stream function (eq. 5 of \cite fox-kemper2011):
 !! \f[
 !!    {\bf \Psi}_o = C_e \frac{ H^2 \nabla \bar{b} \times \hat{\bf z} }{ |f| } \mu(z)
 !! \f]
@@ -2001,7 +2001,7 @@ end function test_answer
 !! \f$ \nabla \bar{b} \f$ is a depth mean buoyancy gradient averaged over the mixed layer.
 !!
 !! For use in coarse-resolution models, an upscaling of the buoyancy gradients and adaption for the equator
-!! leads to the following parameterization (eq. 6 of Fox-Kemper et al., 2011):
+!! leads to the following parameterization (eq. 6 of \cite fox-kemper2011):
 !! \f[
 !!    {\bf \Psi} = C_e \Gamma_\Delta \frac{\Delta s}{l_f} \frac{ H^2 \nabla \bar{b} \times \hat{\bf z} }
 !!                 { \sqrt{ f^2 + \tau^{-2}} } \mu(z)
@@ -2057,7 +2057,7 @@ end function test_answer
 !! available parameters.
 !! MLE_USE_PBL_MLD must be True to use the B23 modification.
 !!
-!! Bodner et al., 2023, (B23) use an expression for the frontal width which changes the scaling from \f$ H^2 \f$
+!! \cite Bodner2023, (B23) use an expression for the frontal width which changes the scaling from \f$ H^2 \f$
 !! to \f$ h H^2 \f$:
 !! \f[
 !!    {\bf \Psi} = C_r \frac{\Delta s |f| \bar{h} \bar{H}^2 \nabla \bar{b} \times \hat{\bf z} }

src/parameterizations/lateral/MOM_self_attr_load.F90

@@ -245,19 +245,21 @@ end subroutine SAL_end
 
 !> \namespace self_attr_load
 !!
+!! \section section_SAL Self attraction and loading
+!!
 !! This module contains methods to calculate self-attraction and loading (SAL) as a function of sea surface height (SSH)
 !! (rather, it should be bottom pressure anomaly). SAL is primarily used for fast evolving processes like tides or
 !! storm surges, but the effect applies to all motions.
 !!
-!!     If SAL_SCALAR_APPROX is true, a scalar approximation is applied (Accad and Pekeris 1978) and the SAL is simply
+!!     If SAL_SCALAR_APPROX is true, a scalar approximation is applied (\cite Accad1978) and the SAL is simply
 !! a fraction (set by SAL_SCALAR_VALUE, usually around 10% for global tides) of local SSH . For tides, the scalar
 !! approximation can also be used to iterate the SAL to convergence [see USE_PREVIOUS_TIDES in MOM_tidal_forcing,
-!! Arbic et al. (2004)].
+!! \cite Arbic2004].
 !!
 !!    If SAL_HARMONICS is true, a more accurate online spherical harmonic transforms are used to calculate SAL.
 !! Subroutines in module MOM_spherical_harmonics are called and the degree of spherical harmonic transforms is set by
 !! SAL_HARMONICS_DEGREE. The algorithm is based on SAL calculation in Model for Prediction Across Scales (MPAS)-Ocean
-!! developed by Los Alamos National Laboratory and University of Michigan [Barton et al. (2022) and Brus et al. (2023)].
+!! developed by Los Alamos National Laboratory and University of Michigan [\cite Barton2022 and \cite Brus2023].
 !!
 !! References:
 !!