=================== Governing Equations =================== Cocoa solves the 2D depth-integrated shallow water equations [Vreugdenhil1994]_ [Toro2001]_. Derivation ---------- The shallow water equations assume: 1. Horizontal length scales are much larger than vertical scales 2. Vertical accelerations are negligible (hydrostatic pressure) 3. Density is constant (barotropic flow) Conservation Laws ----------------- Mass Conservation ^^^^^^^^^^^^^^^^^ The continuity equation expresses conservation of mass: .. math:: :label: continuity \frac{\partial \zeta}{\partial t} + \frac{\partial (UH)}{\partial x} + \frac{\partial (VH)}{\partial y} = 0 where: - :math:`\zeta` is the water surface elevation above the geoid - :math:`H = h + \zeta` is the total water depth - :math:`h` is the bathymetric depth (positive downward) - :math:`U, V` are the depth-averaged velocity components .. figure:: ../_static/images/diagrams/water_column.svg :alt: Water column variables showing bathymetry h, surface elevation zeta, and total depth H :width: 500px :align: center Water column variables: bathymetry :math:`h` (positive downward from geoid), surface elevation :math:`\zeta`, and total depth :math:`H = h + \zeta`. Momentum ^^^^^^^^ The momentum equations express Newton's second law: **x-momentum**: .. math:: :label: x-momentum \begin{split} \frac{\partial U}{\partial t} + U\frac{\partial U}{\partial x} + V\frac{\partial U}{\partial y} - fV &= -g\frac{\partial \zeta}{\partial x} - \frac{1}{\rho_0}\frac{\partial p_s}{\partial x} \\ &\quad + \frac{\tau_{sx}}{\rho_0 H} - \frac{\tau_{bx}}{\rho_0 H} + \nu_h \nabla^2 U \end{split} **y-momentum**: .. math:: :label: y-momentum \begin{split} \frac{\partial V}{\partial t} + U\frac{\partial V}{\partial x} + V\frac{\partial V}{\partial y} + fU &= -g\frac{\partial \zeta}{\partial y} - \frac{1}{\rho_0}\frac{\partial p_s}{\partial y} \\ &\quad + \frac{\tau_{sy}}{\rho_0 H} - \frac{\tau_{by}}{\rho_0 H} + \nu_h \nabla^2 V \end{split} Term Descriptions ----------------- .. list-table:: :header-rows: 1 :widths: 30 30 40 * - x-momentum Term - y-momentum Term - Physical Meaning * - :math:`\partial U/\partial t` - :math:`\partial V/\partial t` - Local acceleration * - :math:`U \frac{\partial U}{\partial x} + V \frac{\partial U}{\partial y}` - :math:`U \frac{\partial V}{\partial x} + V \frac{\partial V}{\partial y}` - Advective acceleration * - :math:`-fV` - :math:`+fU` - Coriolis acceleration * - :math:`-g \frac{\partial \zeta}{\partial x}` - :math:`-g \frac{\partial \zeta}{\partial y}` - Barotropic pressure gradient * - :math:`-\frac{1}{\rho_0}\frac{\partial p_s}{\partial x}` - :math:`-\frac{1}{\rho_0}\frac{\partial p_s}{\partial y}` - Atmospheric pressure gradient (see :doc:`meteorological_forcing`) * - :math:`\tau_{sx}/(\rho_0 H)` - :math:`\tau_{sy}/(\rho_0 H)` - Wind stress (see :doc:`meteorological_forcing`) * - :math:`-\tau_{bx}/(\rho_0 H)` - :math:`-\tau_{by}/(\rho_0 H)` - Bottom friction * - :math:`\nu_h \nabla^2 U` - :math:`\nu_h \nabla^2 V` - Lateral diffusion Bottom Friction --------------- Cocoa uses a quadratic bottom friction formulation with Manning's n: .. math:: \tau_{bx} = \rho_0 C_f U \sqrt{U^2 + V^2} .. math:: \tau_{by} = \rho_0 C_f V \sqrt{U^2 + V^2} where the friction coefficient :math:`C_f` is derived from Manning's n: .. math:: :label: manning-friction C_f = \frac{g n^2}{H^{1/3}} Here :math:`n` is the Manning's roughness coefficient and :math:`H` is the total water depth. This formulation accounts for the depth-dependence of bottom friction, with shallower water experiencing stronger frictional effects. .. figure:: ../_static/images/diagrams/manning_friction.svg :alt: Manning's friction coefficient versus depth for different roughness values :width: 500px :align: center Manning's friction coefficient :math:`C_f` as a function of depth for several roughness values :math:`n`. The coefficient increases sharply in shallow water and is floored at :math:`C_{f,\min} = 0.001`. .. _internal-tide-friction: Internal Tide Friction ^^^^^^^^^^^^^^^^^^^^^^ In regions where barotropic tidal energy is converted to internal (baroclinic) tides through interaction with topographic features, the energy loss from the barotropic tide can be parameterized as an additional linear friction term. This internal tide friction is added to the bottom friction TKM tensor after the Manning's friction has been computed: .. math:: \tau_{xx} \leftarrow \tau_{xx} + \tau_{IT,xx}, \quad \tau_{yy} \leftarrow \tau_{yy} + \tau_{IT,yy}, \quad \tau_{xy} \leftarrow \tau_{xy} + \tau_{IT,xy} The internal tide friction coefficient is typically derived from tidal energy dissipation estimates (e.g., from satellite altimetry or numerical models) and is specified as a spatially-varying nodal attribute in the mesh file. Two storage modes are supported: - **Scalar** (1 value per node): isotropic friction added to the diagonal components (:math:`\tau_{IT,xx} = \tau_{IT,yy} = \tau_{IT}`, :math:`\tau_{IT,xy} = 0`) - **Tensor** (3 values per node): anisotropic friction with independent :math:`\tau_{IT,xx}`, :math:`\tau_{IT,yy}`, and :math:`\tau_{IT,xy}` components For global meshes using coordinate rotation, the tensor form of internal tide friction must be rotated from the geographic frame to the computational frame. This is done once during initialization using a rank-1 tensor decomposition: the tensor is decomposed into a vector :math:`\mathbf{H} = (H_x, H_y)`, rotated using the per-node velocity transformation matrix, and reconstructed. This matches ADCIRC's ``Apply2DInternalWaveDrag`` rotation for the ``IFSPROTS=1`` case. See :doc:`../getting_started/configuration` for configuration details. Coriolis Parameter ------------------ The Coriolis parameter is computed as: .. math:: f = 2\Omega \sin(\phi) where :math:`\Omega = 7.292 \times 10^{-5}` rad/s is Earth's angular velocity and :math:`\phi` is the latitude.