Wave Orbital Velocity — `uorb`¶

Significant horizontal wave orbital velocity at any height above the seabed (or depth below the surface), computed from integrated spectral parameters using the monochromatic peak-period approximation (Soulsby 1997).

Governing equation¶

The horizontal orbital velocity at height z above the seabed in water of depth h is:

\[ U(z) = \frac{\pi H_s}{T} \cdot \frac{\cosh(k z)}{\sinh(k h)} \]

where k is the angular wavenumber satisfying the linear dispersion relation ω² = g k tanh(kh) with ω = 2π/T.

At the seabed (z = 0, the default), cosh(0) = 1 and the formula reduces to the classical near-bed form used in sediment-transport and bed-shear-stress models:

\[ U_b = \frac{\pi H_s}{T \sinh(k h)} \]

This is exact for a monochromatic wave of height Hs propagating in depth h (Soulsby 1997, eq. 2.44).

Parameters¶

Parameter	Default	Description
`hs`	`"hs"`	Significant wave height variable name (m)
`tp`	`"tp"`	Representative wave period variable name (s)
`depth`	`"depth"`	Water depth variable name (m, positive downward) or scalar
`z`	`0.0`	Position in metres — variable name or scalar. Interpretation set by `reference`.
`reference`	`"bed"`	Reference datum for `z`: `"bed"` = height above seabed, `"surface"` = depth below surface
`g`	`9.81`	Gravitational acceleration (m/s²)
`solver`	`"explicit"`	Dispersion solver: `"explicit"` or `"exact"`

Depth profiles and reference datum¶

The reference parameter controls how z is interpreted:

reference: 'bed' (default) — z is height above the seabed. z = 0 is the seabed, the standard input for sediment-transport and bed-shear-stress models.
reference: 'surface' — z is depth below the still-water surface. z = 0 is the surface. Internally converted as z_bed = depth − z, so spatially varying bathymetry is handled automatically.

calls:
  - func: mean
    data_vars: [uorb_bed, uorb_1m, uorb_10m]
    derived_vars:
      - name: uorb_bed
        func: uorb
        z: 0.0
        reference: bed        # seabed (default)
      - name: uorb_1m
        func: uorb
        z: 1.0
        reference: bed        # 1 m above bed
      - name: uorb_10m
        func: uorb
        z: 10.0
        reference: surface    # 10 m below the surface

The reference: 'surface' form is particularly convenient when you have a moored instrument or fixed platform at a known depth regardless of local bathymetry.

Points outside the water column¶

The evaluation point must lie between the seabed and the still-water surface. Cells where z_bed < 0 (below the bed) or z_bed > h (above the surface) are returned as NaN, evaluated per timestep so a cell may be valid at some times and not others when the depth varies in time. The bounds are inclusive: the seabed itself and the still-water surface are both retained.

This matters whenever a fixed z meets varying bathymetry. z: 10.0 with reference: surface sits below the bed anywhere shallower than 10 m, and because cosh is an even function such a point would otherwise return the value for its mirror image above the bed — a velocity larger than the true surface value, not smaller. Masking is unconditional: there is no physical reading of the number outside the water column.

Choice of representative period¶

The result is sensitive to the choice of T. Wave models typically output the peak period T_p. For improved accuracy, the mean zero-upcrossing period T_z = √(m₀/m₂) is preferred because it weights all spectral components more evenly. Conversion factors for common spectral shapes (Soulsby 1997, Table 2.1):

Spectral shape	T_z / T_p
JONSWAP (γ = 3.3, typical wind sea)	≈ 1/1.28
Pierson–Moskowitz (fully developed)	≈ 1/1.05

If only T_p is available, pre-compute T_z as a separate derived variable before calling uorb.

Dispersion solvers¶

Two dispersion-relation solvers are available via the solver parameter:

'explicit' (default) — Chen & Thomson (1993) polynomial approximation:

\[ a = 1 + 0.6522\, k_0 h + 0.4622\, (k_0 h)^2 + 0.0864\, (k_0 h)^4 + 0.0675\, (k_0 h)^5 $$ $$ k = \frac{k_0 h \cdot \sqrt{1 + 1/(k_0 h \cdot a)}}{h}, \quad k_0 h = \omega^2 h / g \]

Maximum error < 0.2 % across all depth regimes — negligible compared with Hs/Tp uncertainties (typically ≥ 5–10 %). Implemented as pure xarray/numpy ufuncs: no apply_ufunc, fully dask-transparent, ~40× fewer FLOPs than the iterative solver. Recommended for all production runs.

'exact' — Newton-Raphson iteration to full float64 machine precision. The Python loop is confined inside a numpy function dispatched by apply_ufunc, so the dask graph stays flat. Use for validation or sensitivity studies.

Numerical stability¶

The transfer function cosh(kz)/sinh(kh) is evaluated in the equivalent form:

\[ \frac{e^{kz - kh} + e^{-kz - kh}}{1 - e^{-2kh}} \]

This avoids float64 overflow for large kh (sinh overflows for kh ≳ 710) while remaining exact across all depth regimes. At large kh the numerator approaches exp(−k(h−z)), recovering the familiar exponential decay of orbital motion in deep water.

Accuracy and limitations¶

This formula is exact for a single sinusoidal wave. For a random sea, Wiberg & Sherwood (2008) show the true RMS near-bed orbital velocity (from spectral integration) can differ from the monochromatic approximation by 10–30 %, depending on spectral shape and relative depth. When the full variance spectrum S(f) is available, the spectral integral formulation is preferred:

\[ \sigma_u^2(z) = \int_0^{\infty} (2\pi f)^2 \left[\frac{\cosh(k(f)\,z)}{\sinh(k(f)\,h)}\right]^2 S(f)\,\mathrm{d}f \]

References¶

Soulsby, R. L. (1997). Dynamics of Marine Sands. Thomas Telford, London. — Near-bed orbital velocity (eq. 2.44) and period conversion factors (Table 2.1).
Wiberg, P. L., & Sherwood, C. R. (2008). Calculating wave-generated bottom orbital velocities from surface-wave parameters. Computers & Geosciences, 34, 1243–1262. https://doi.org/10.1016/j.cageo.2008.02.010
Nielsen, P. (1992). Coastal Bottom Boundary Layers and Sediment Transport. World Scientific. — Near-bed wave kinematics.
Chen, G., & Thomson, J. (1993). A two-dimensional model of wave transformation in shallow water. Ocean Engineering, 20(6), 487–507. — Explicit polynomial approximation to the dispersion relation.
Beji, S. (2013). Improved explicit approximation of linear dispersion relationship for gravity waves. Coastal Engineering, 73, 11–12. https://doi.org/10.1016/j.coastaleng.2012.10.002

API reference¶

`gridstats.derived.uorb.uorb(ds: xr.Dataset, *, hs: str = 'hs', tp: str = 'tp', depth: str | float = 'depth', z: str | float = 0.0, reference: str = 'bed', g: float = 9.81, solver: str = 'explicit') -> xr.DataArray` ¶

Significant horizontal wave orbital velocity at position z.

Monochromatic approximation (Soulsby 1997) using integrated spectral parameters Hs and a representative period T:

.. math::

U(z) = \frac{\pi H_s}{T} \cdot \frac{\cosh(k z_{bed})}{\sinh(k h)}

where k solves the linear dispersion relation ω² = g k tanh(kh) and z_bed is the height above the seabed. See the derived variables documentation for period choice, depth profiles, solver comparison, and accuracy notes.

The evaluation point must lie within the water column: cells where z_bed < 0 (below the seabed) or z_bed > h (above the still-water surface) are returned as NaN. This matters for a fixed z over varying bathymetry — z=15 with reference='surface' is below the bed wherever the water is shallower than 15 m, and because cosh is even such a point would otherwise return the value for its mirror image above the bed, exceeding the true surface velocity. The bounds are inclusive, so the seabed itself (z_bed = 0) and the still-water surface (z_bed = h) are both retained. The test is applied per timestep, so a cell may be valid at some times and not others when the depth varies in time.

Parameters:

Name	Type	Description	Default
`ds`	`Dataset`	Input dataset.	required
`hs`	`str`	Name of the significant wave height variable (m).	`'hs'`
`tp`	`str`	Name of the representative wave period variable (s).	`'tp'`
`depth`	`str \| float`	Name of a depth variable (m, positive downward) or a scalar depth to apply uniformly across the domain.	`'depth'`
`z`	`str \| float`	Position at which to evaluate orbital velocity (m, default 0). Variable name or scalar float. Interpretation depends on `reference`: height above the seabed when `reference='bed'`, or depth below the still-water surface when `reference='surface'`.	`0.0`
`reference`	`str`	Reference datum for z: `'bed'` (default) — z is height above the seabed (0 = seabed, h = surface). `'surface'` — z is depth below the still-water surface (0 = surface, h = seabed). Converted internally via z_bed = depth − z, so spatially varying bathymetry is handled automatically.	`'bed'`
`g`	`float`	Gravitational acceleration (m/s², default 9.81).	`9.81`
`solver`	`str`	`'explicit'` (default, Chen & Thomson 1993, < 0.2 % error, ~40× faster) or `'exact'` (Newton-Raphson, float64 precision).	`'explicit'`

Returns:

Type	Description
`DataArray`	Horizontal orbital velocity DataArray (m/s, float32). NaN where
`DataArray`	depth ≤ 0, where the evaluation point falls outside the water column
`DataArray`	(below the seabed or above the still-water surface), or where input
`DataArray`	variables contain NaN.

Raises:

Type	Description
`ValueError`	If solver is not `'explicit'` or `'exact'`.
`ValueError`	If reference is not `'bed'` or `'surface'`.

References

Soulsby, R. L. (1997). Dynamics of Marine Sands. Thomas Telford. Chen, G., & Thomson, J. (1993). Ocean Engineering, 20(6), 487–507.

Wave Orbital Velocity — uorb¶