InternalModes

Create vertical-mode solvers from gridded or analytical stratification.

---

Declaration

classdef InternalModes < handle

Overview

InternalModes is the user-facing wrapper around the concrete solver classes. It initializes one of the numerical, analytical, or asymptotic implementations, then forwards the common public interface for requesting \(F_j(z)\), \(G_j(z)\), \(h_j\), SQG modes, and background-stratification diagnostics.

The wrapper follows the vertical eigenvalue problems described in Section 2.3 of Early, Lelong, and Smith (2020):

\[\partial_{zz} G_j = -\frac{N^2 - \omega^2}{g h_j} G_j\]

for fixed \(\omega\), and

\[\partial_{zz} G_j - K^2 G_j = -\frac{N^2 - f_0^2}{g h_j} G_j\]

for fixed \(K\).

The primary construction path is either:

• gridded density: InternalModes(rho, zIn, zOut, latitude, ...)
• analytical density or N2: InternalModes(rhoOrN2, [zBottom 0], zOut, latitude, ...)

The wrapper also supports built-in benchmark profiles through the shorthand

im = InternalModes("constant", "wkbAdaptiveSpectral", 128);

and exposes quick comparison figures for those benchmark cases.

im = InternalModes(rho, zIn, zOut, latitude, "method", "wkbAdaptiveSpectral");
[F, G, h, omega] = im.modesAtWavenumber(2*pi/1000);
psi = im.surfaceModesAtWavenumber(2*pi/1000);

Topics

• Create and initialize modes
  • InternalModes Initialize the wrapper from a profile or a built-in benchmark case.
  • method Name of the selected concrete solver implementation.
• Inspect grids and stratification
  • Lz Total water-column depth.
  • N2 Buoyancy frequency squared sampled on zOut.
  • N2Function Function handle for the benchmark buoyancy-frequency profile \(N^2(z)\).
  • f0 Coriolis parameter at the selected latitude.
  • latitude in degrees used to compute f0.
  • rho Background density sampled on zOut.
  • rho0 Reference surface density.
  • rhoFunction Function handle for the benchmark density profile \(\bar{\rho}(z)\).
  • rho_z First depth derivative of the background density sampled on zOut.
  • rho_zz Second depth derivative of the background density sampled on zOut.
  • z Output depth grid on which public profiles and modes are returned.
• Configure normalization and boundaries
  • lowerBoundary Lower boundary condition at the ocean bottom.
  • normalization Mode normalization convention.
  • upperBoundary Upper boundary condition at the ocean surface.
• Compute modes
  • bottomModesAtWavenumber Return the bottom SQG mode at fixed horizontal wavenumber.
  • modesAtFrequency Return vertical modes for a fixed frequency.
  • modesAtWavenumber Return vertical modes for a fixed horizontal wavenumber.
  • nModes Optional cap on the number of modes returned.
  • projectOntoGModesAtWavenumber Project a profile onto the G modes at fixed horizontal wavenumber.
  • showLowestModesAtFrequency Plot the lowest resolved modes at a fixed frequency.
  • showLowestModesAtWavenumber Plot the lowest resolved modes at a fixed horizontal wavenumber.
  • surfaceModesAtWavenumber Return the surface SQG mode at fixed horizontal wavenumber.
• Inspect analytical solutions
  • ConditionNumberAsFunctionOfModeNumber Compute condition number as a function of retained mode count.
  • NumberOfWellConditionedModes Estimate how many columns of a mode matrix remain numerically well conditioned.
  • RenormalizeForGoodConditioning Renormalize a mode matrix by matching column norms to a common scale.
  • StratificationProfileWithName Return one of the built-in benchmark stratification profiles.
  • showRelativeErrorAtFrequency Plot benchmark relative errors for a built-in profile at fixed \(\omega\).
  • showRelativeErrorAtWavenumber Plot benchmark relative errors for a built-in profile at fixed \(K\).
  • stratification Name of the active built-in benchmark stratification profile.

Developer Topics

These items document internal implementation details and are not part of the primary public API.

• Developer topics
  • ConditionNumberAsFunctionOfModeNumberForModeIndices Compute mode-matrix condition numbers for selected truncation indices.
  • ProfileWithDoubleExponentialPlusPycnocline Build a two-exponential pycnocline profile used by the built-in benchmarks.
  • ProfileWithDoubleGaussianExponentialPlusPycnocline Build a mixed Gaussian-exponential pycnocline profile used by the built-in benchmarks.
  • ProfileWithDoubleGaussianPlusPycnocline Build a double-Gaussian pycnocline profile used by the built-in benchmarks.
  • internalModes Concrete solver instance created by the wrapper.
  • isRunningTestCase Flag indicating whether the wrapper was initialized from a built-in benchmark case.
  • shouldShowDiagnostics Toggle diagnostic messages from the concrete solver.

---