Adds a submesoscale eddy design document

[vanroekel]

This is a draft design document for the upcoming submesoscale eddy parameterization. The compiled version is on nersc here. The document details two formulations, the original by Fox-Kemper et al (2011) and a new update by Bodner et al (2023). The latter formulation requires the boundary layer depth so cannot be implemented until KPP is implemented to Omega.

This PR also includes a change to conf.py to allow for equation numbering to restart in each individual design doc.

Checklist

• Documentation:
  • Design document has been generated and added to the docs
  • Documentation has been built locally and changes look as expected
• Linting
  • Pre-commit run locally
• Building
  • CMake build does not produce any new warnings from changes in this PR

[vanroekel]

@xylar a small question for you - I see diffs in the .precommit-config.yaml file that I didn't expect. Is this a rebase issue on my side?

[cbegeman]

Suggested change

	\Psi_e = C_e \frac{H^2}{|f|} |\nabla_h b| \cdot \mu(z)
	\Psi_e = C_e \frac{H^2}{|f|} |\nabla_h b_{ml}| \cdot \mu(z)

[vanroekel]

changed

[cbegeman]

Suggested change

	\Psi(z) = C_e \frac{\Delta_s}{L_f} \frac{H^2 \nabla_h \overline{b_{ml}\times \hat{z}}}{\sqrt{f^2 + \tau^{-2}}} \mu(z)
	\Psi_e(z) = C_e \frac{\Delta_s}{L_f} \frac{H^2 \nabla_h \overline{b_{ml}\times \hat{z}}}{\sqrt{f^2 + \tau^{-2}}} \mu(z)

[cbegeman]

Suggested change

	\Psi(z) = C_r \frac{\Delta_s \left|f\right| h H^2 \nabla b_{ml} \times \hat{z} }{(m_* u_u^3 + n_* w_*^3)^{2/3}}\mu(z)
	\Psi(z) = C_r \frac{\Delta_s \left|f\right| h H^2 \nabla b_{ml} \times \hat{z} }{(m_* u_*^3 + n_* w_*^3)^{2/3}}\mu(z)

[cbegeman]

Suggested change

	In [](#mld-definition), $p_0$ is a reference pressure, which is set to $10^5$ Pa ($\approx 10$m), and $\Delta \rho_t$ is a density threshold criterion, which is typically set to 0.03 kg m$^{-3}$. When the density threshold occurs between layers, the mixed layer depth is found via a linear fit between the bounding layers.
	In [](#mld-definition), $p_0$ is a reference pressure, which is set to $10^5$ Pa ($\approx 10$m), $\rho(p_0)$ is the local density at that pressure level, and $\Delta \rho_t$ is a density threshold criterion, which is typically set to 0.03 kg m$^{-3}$. When the density threshold occurs between layers, the mixed layer depth is found via a linear fit between the bounding layers.

[cbegeman]

I think it would be a safe guess to just build land ice pressure in additively: $p_0 = p_{ice} + p_t$ where $p_t = 10^5$ Pa

[cbegeman]

Sounds like this would be a CTest?

[cbegeman]

Would it be helpful to specify whether buoyancy gradient and the streamfunction are originally computed on cells, edges or vertices?

[katsmith133]

This looks great, @vanroekel! Thanks for this work. Most of my comments are minor and can be taken or left depending on how you feel they fit.

[katsmith133]

Suggested change

	b_{ml} = g - \frac{1}{H}\int_{-H}^0 g \frac{\rho_0}{\rho} d \tilde{z} = g - \frac{1}{H}\int_{-H}^0 g \rho_0 \alpha
	b_{ml} = g - \frac{1}{H}\int_{-H}^0 g \frac{\rho_0}{\rho} d \tilde{z} = g - \frac{1}{H}\int_{-H}^0 g \rho_0 \alpha d \tilde{z}

[katsmith133]

Suggested change

	where $\nabla_h$ is a gradient along a fixed model layer in Omega. The vertical derivative of buoyancy will utilize the Brunt Vaisala Frequency variable from the vertical mixing calculation.
	where $\nabla_h$ is a gradient along a fixed model layer in Omega. The vertical derivative of buoyancy will utilize the Brunt Vaisala Frequency variable calculated in the Equation of State.

[katsmith133]

Suggested change

	### 2.3 Requirement: The parameterization must be configurable in the traditiona FK11 form and the B23 update
	### 2.3 Requirement: The parameterization must be configurable in the traditional FK11 form and the B23 update

[katsmith133]

Do we have a typical/suggested value for $\tau_{min}$ or is this something we will need to tune? Maybe also note that this differs from the FK11 formula.

[katsmith133]

Suggested change

The basic definition of the submesoscale parameterization is given in [](#submeso-definition). In this equation, $L_f$, $C_e$, and $\tau$ are parameters. Some models, such as MOM6 merge $\frac{\Delta_s}{L_f}$ into a single parameter. This is not done in Omega to allow for variations in the grid size ($\Delta_s$) common to many target unstructured meshes. As in MPAS-Ocean, the characteristic frontal width ($L_f$) is given by

The basic definition of the submesoscale parameterization is given in [](#submeso-definition). In this equation, $C_e$, $L_f$, $\Delta_s$, and $\tau$ are parameters. Some models, such as MOM6 merge $\frac{\Delta_s}{L_f}$ into a single parameter. This is not done in Omega to allow for variations in the grid size ($\Delta_s$) common to many target unstructured meshes. $C_e$ is defined above and is typically hard-coded to a value like 0.06. As in MPAS-Ocean, the characteristic frontal width ($L_f$) is taken as the maximum of three length scales

[katsmith133]

Suggested change

The most complex part of this design is the spatial dependence implicit in the averaging of the buoyancy. The necessary `parallelReduce` calculation requires reduction over a spatially variable inner range. This will be accomplished with the hierarchical parallelism wrappers described in CITE HP design doc. In the initial implementation, only the FK11 form will be included. The B23 formulation requires the boundary layer depth, which can not be included until KPP [Large et al, 1994](https://agupubs.onlinelibrary.wiley.com/doi/10.1029/94RG01872) is implemented for vertical mixing.

The most complex part of this design is the spatial dependence implicit in the averaging of the buoyancy. The necessary `parallelReduce` calculation requires reduction over a spatially variable inner range. This will be accomplished with the hierarchical parallelism wrappers described in CITE HP design doc. In the initial implementation, only the FK11 form will be included. The B23 formulation requires the boundary layer depth, which can not be included until KPP ([Large et al, 1994](https://agupubs.onlinelibrary.wiley.com/doi/10.1029/94RG01872) is implemented for vertical mixing).

[katsmith133]

Two additional parameters:

• Something like EnableSubmesos (we need to be able to turn them off completely as well, no?)
• $\rho_0$, but maybe note that this can be grabbed from the vertical coord section its defined in in the config Yaml.

[vanroekel]

Yep, thanks. I've made the changes

[katsmith133]

Suggested change

	The public `computeDenMLD` mthod will utilize the specific volume frmo the TEOS-10 calculation to compute a mixed layer depthy based on the threshold criterion. Given Omega has easy access to `SpecVol` and not density, we rearrange the standard density threshold calculation
	The public `computeDenMLD` method will utilize the specific volume from the TEOS-10 calculation to compute a mixed layer depth based on the threshold criterion. Given Omega has easy access to `SpecVol` and not density, we rearrange the standard density threshold calculation

[katsmith133]

Suggested change

	where $\rho_0$ is the reference density used in the pseudo height coordinate definition. This can be easily rearranged to
	where $\rho_0$ is the reference density used in the pseudo height coordinate definition. Again, since Omega calculates `SpecVol` and not density itself, this can be easily rearranged to

[katsmith133]

Suggested change

	This form is preferred since Omega calculates `SpecVol` and not density itself. Since the buoyancy is only used for a horizontal gradient the reference pressure is not a consideration.
	Since the buoyancy is only used for a horizontal gradient the reference pressure is not a consideration.

[katsmith133]

This looks great, @vanroekel! Thanks for this work. Most of my comments are minor and can be taken or left depending on how you feel they fit.

[vanroekel]

Thanks @katsmith133 and @cbegeman for the great comments. I believe I've addressed them all. I'd appreciate a rereview when you have a chance. @alicebarthel I'd also appreciate a review from you as well.

[cbegeman]

Your changes look good to me. Thanks!