Source code for opendrift.readers.reader_tpxo

"""
Reader for barotropic tidal currents from the TPXO9 global tide model, e.g.
to add tides to an ocean model without tides (such as TOPAZ5) with reader
arithmetic::

    tides = reader_tpxo.Reader('/path/to/tpxo9', corners=[-15, 40, 55, 86])
    o.add_reader([topaz + tides, topaz])

``topaz + tides`` provides only the variables both readers have (the
currents), so ``topaz`` is added again for its other variables. TPXO currents
are depth-averaged, so the same tidal current is returned at all depths.

The harmonic synthesis follows the OTIS/TMD convention TPXO is distributed for
(as pyTMD with corrections='OTIS'): constituent phase is
omega * (t - 1992-01-01) + phase0 + u, with nodal factors f and angles u from
the lunar node only, computed with pyTMD (which must be installed).

Reads the OTIS netCDF velocity file of TPXO9.v1 (``u_tpxo9.v1.nc``: ``ua``/``up``
eastward and ``va``/``vp`` northward velocity amplitude (cm/s) and Greenwich
phase lag (degrees) on a regular global lon/lat C-grid).
"""

import os
import logging
from datetime import datetime

import numpy as np

from opendrift.readers.basereader.continuous import ContinuousReader

logger = logging.getLogger(__name__)

TPXO_UV_FILE = 'u_tpxo9.v1.nc'

# The eight major semidiurnal and diurnal constituents
MAJOR_CONSTITUENTS = ('m2', 's2', 'n2', 'k2', 'k1', 'o1', 'p1', 'q1')

OTIS_EPOCH = datetime(1992, 1, 1)
MJD_OTIS_EPOCH = 48622.0


[docs] def tidal_phasors(time, constituents): """f * exp(i * (omega t + phase0 + u)) per constituent at ``time`` (naive UTC datetime), as in pyTMD.predict.ocean_load.time_series with corrections='OTIS'. Multiply by a complex harmonic constant (amp * exp(-i * phase_lag)) and take the real part to get the tide.""" import pyTMD days = (time - OTIS_EPOCH).total_seconds() / 86400.0 u, f, _ = pyTMD.constituents.arguments( np.atleast_1d(days + MJD_OTIS_EPOCH), constituents, corrections='OTIS') _, phase0, omega, _, _ = pyTMD.constituents._constituent_parameters(constituents) return f[0] * np.exp(1j * (86400.0 * omega * days + phase0 + u[0]))
[docs] class HarmonicGrid: """Complex harmonic constants of one TPXO C-grid component on a regular lon/lat grid, bilinearly interpolated to arbitrary positions. Complex values (not amplitude/phase) are interpolated, so phase wrap-around doesn't matter; land nodes are 0 in TPXO and stay 0.""" def __init__(self, ds, amp_var, phase_var, lon_var, lat_var, con_index, corners=(-180, 180, -90, 90), amp_scale=0.01): # The file is (nc, nx, ny) with ny fastest: read whole longitude # blocks and cut the latitudes in memory, as reading a latitude band # directly means thousands of small strided reads (minutes on GPFS) lon_min, lon_max, lat_min, lat_max = corners lon = ds[lon_var][:][:, 0].astype(np.float64) lat = ds[lat_var][0, :].astype(np.float64) self.dlon = (lon[-1] - lon[0]) / (len(lon) - 1) self.dlat = (lat[-1] - lat[0]) / (len(lat) - 1) nlon = len(lon) j0 = max(int(np.searchsorted(lat, lat_min)) - 1, 0) j1 = min(int(np.searchsorted(lat, lat_max)) + 1, len(lat)) nx = int(np.ceil((lon_max - lon_min) / self.dlon)) + 3 self.periodic = nx >= nlon if self.periodic: i0, nx = 0, nlon else: i0 = (int(np.floor((lon_min - lon[0]) / self.dlon)) - 1) % nlon # One or two (across the 0/360 seam) contiguous longitude blocks blocks = [(i0, min(i0 + nx, nlon))] if i0 + nx > nlon: blocks.append((0, i0 + nx - nlon)) def read(var, k): return np.concatenate([ds[var][k, a:b, :][:, j0:j1] for a, b in blocks]) # (nc, nx, ny) in the file -> (nc, ny, nx) amp = np.stack([read(amp_var, k) for k in con_index]).transpose(0, 2, 1) phase = np.stack([read(phase_var, k) for k in con_index]).transpose(0, 2, 1) self.values = (amp * amp_scale * np.exp(-1j * np.radians(phase))).astype(np.complex64) self.lon0, self.lat0 = lon[0] + i0 * self.dlon, lat[0] + j0 * self.dlat self.nlat, self.nlon = self.values.shape[1], self.values.shape[2]
[docs] def interpolate(self, lon, lat): """(nc, n) complex constants at lon/lat (degrees).""" if self.periodic: x = np.mod(lon - self.lon0, 360.0) / self.dlon else: # positions outside the loaded block get its edge values half = (self.nlon - 1) * self.dlon / 2 x = (np.mod(lon - self.lon0 - half + 180, 360.0) - 180 + half) / self.dlon x = np.clip(x, 0.0, self.nlon - 1.000001) y = np.clip((lat - self.lat0) / self.dlat, 0.0, self.nlat - 1.000001) i0 = np.floor(x).astype(int) j0 = np.floor(y).astype(int) wx = (x - i0).astype(np.float32) wy = (y - j0).astype(np.float32) i0 %= self.nlon i1 = (i0 + 1) % self.nlon j1 = j0 + 1 v = self.values return ((1 - wy) * ((1 - wx) * v[:, j0, i0] + wx * v[:, j0, i1]) + wy * ((1 - wx) * v[:, j1, i0] + wx * v[:, j1, i1]))
# One copy per process and set of arguments: readers rebuilt with the same # coverage (e.g. once per simulation chunk) reuse it instead of re-reading. _cache = {}
[docs] def _load(tpxo_dir, constituents, corners): """(constituents, u grid, v grid), loaded within corners and cached""" key = (os.path.abspath(tpxo_dir), None if constituents is None else tuple(constituents), tuple(corners)) if key in _cache: return _cache[key] import netCDF4 with netCDF4.Dataset(os.path.join(tpxo_dir, TPXO_UV_FILE)) as ds: ds.set_auto_mask(False) names = [b''.join(c).decode().strip().lower() for c in ds['con'][:]] if constituents is None: missing = [c for c in MAJOR_CONSTITUENTS if c not in names] if missing: logger.warning(f'Tidal constituents {missing} not in {TPXO_UV_FILE}, ' 'using the others') constituents = tuple(c for c in MAJOR_CONSTITUENTS if c in names) if not constituents: raise ValueError(f'None of {MAJOR_CONSTITUENTS} in {TPXO_UV_FILE} ({names})') else: constituents = tuple(c.lower() for c in constituents) missing = [c for c in constituents if c not in names] if missing: raise ValueError(f'Constituents {missing} not in {TPXO_UV_FILE} ({names})') con_index = [names.index(c) for c in constituents] _cache[key] = (constituents, HarmonicGrid(ds, 'ua', 'up', 'lon_u', 'lat_u', con_index, corners), HarmonicGrid(ds, 'va', 'vp', 'lon_v', 'lat_v', con_index, corners)) return _cache[key]
[docs] class Reader(ContinuousReader): """Eastward/northward TPXO barotropic tidal current (m/s). Args: tpxo_dir: folder with the TPXO OTIS netCDF velocity file (u_tpxo9.v1.nc). constituents: list of constituents, e.g. ['m2', 's2']. Default: those of the eight major ones (m2 s2 n2 k2 k1 o1 p1 q1) that the file has. corners: [lonmin, lonmax, latmin, latmax] to load TPXO for, e.g. the simulation domain. Default global (about 300 MB in memory). """ def __init__(self, tpxo_dir, constituents=None, corners=(-180, 180, -90, 90)): try: import pyTMD # noqa: F401 except ImportError: raise ImportError('The pyTMD package is needed for tidal currents, ' 'see https://pytmd.readthedocs.io') self.constituents, self.u, self.v = _load(tpxo_dir, constituents, corners) self.variables = ['x_sea_water_velocity', 'y_sea_water_velocity'] self.proj4 = '+proj=latlong' self.xmin, self.xmax, self.ymin, self.ymax = corners self.start_time = None self.end_time = None self.time_step = None self.name = f'TPXO tides ({",".join(self.constituents)})' super().__init__()
[docs] def get_variables(self, requested_variables, time=None, x=None, y=None, z=None): phasors = tidal_phasors(time, self.constituents).astype(np.complex64) grids = {'x_sea_water_velocity': self.u, 'y_sea_water_velocity': self.v} variables = {'time': time, 'x': x, 'y': y, 'z': z} for var in requested_variables: variables[var] = np.real(phasors @ grids[var].interpolate( np.asarray(x, dtype=np.float64), np.asarray(y, dtype=np.float64))).astype(np.float64) return variables