pyfvcom2.interpolation module

Interpolation functions

class pyfvcom2.interpolation.CMEMSInterpolator(cmems_reader: CMEMSReader, fvcom_to_cmems_var_names: dict | None = None)

Bases: Interpolator

CMEMS interpolator class

Args:

cmems_reader (CMEMSReader): An instance of CMEMSReader with loaded data. fvcom_name_map (dict): A mapping of variable names between FVCOM and CMEMS. The keys are FVCOM variable names and the values are CMEMS variable names.

interpolate(coordinates: InterpolationCoordinates, fvcom_var_name: str) → ndarray

Perform interpolation operation for CMEMS data.

Args:

coordinates (InterpolationCoordinates): Space and time coordinates for the FVCOM grid; i.e., these are the times and locations where we want interpolated data. fvcom_var_name (str): Name of the FVCOM variable that we want interpolated data for. This will be matched to the corresponding CMEMS variable name using the provided mapping.

Returns:

np.ndarray: Interpolated variable on the FVCOM grid. For 2D this will be (time, points), and for 3D this will be (time, depth, points), where points may be either nodes or elements depending on the variable.

class pyfvcom2.interpolation.FVCOMInterpolator(fvcom_reader: FVCOMReader)

Bases: Interpolator

FVCOM interpolator class

There are several methods that could be used for interpolating data:

1. Nearest-neighbor interpolation

2. Linear interpolation from a delaunay triangulation

3. Radial basis function interpolation

These different methods have different trade-offs in terms of speed and accuracy, with RBFs being the most accurate but also the slowest. For now, we only support linear interpolation using scipy’s LinearTriInterpolator. However, this could be extended in future to support other methods.

Further notes: - In nested FVCOM grids, the elements are identical in the overlap zone, meaning there is no need to interpolate from one grid to another. Instead, one can simply extract the data from the parent grid at the locations of the child grid nodes/elements. - For node-based variables (e.g., zeta, h), interpolation is performed using the grid nodes. We use the input grid’s connectivity (triangles) to build a triangulation for the nodes (i.e., the nv array). - For element-based variables (e.g., u, v), we must construct a new triangulation based on the element centroids (xc, yc). - We should allow for extrapolation of values outside the convex hull of the triangulation, which may be necessary when moving from a coarse grid to a finer grid. This is done by testing for NaN values in the interpolated output and filling them using nearest-neighbor interpolation. A warning is issued when this occurs. - Once data has been interpolated onto all horizontal surfaces of the input grid, we then interpolate vertically onto the supplied depth levels. - Options to parallelise the interpolation step are included.

Args:

fvcom_reader (FVCOMReader): An instance of FVCOMReader with loaded data.

generate_land_sea_mask(coordinates: InterpolationCoordinates) → ndarray

Generate a land-sea mask for the given interpolation coordinates

The mask indicates which points are within the convex hull of the FVCOM grid and which are not, and thus which are sea points and which are land points.

Args:

coordinates (InterpolationCoordinates): The interpolation coordinates for which to generate the mask.

Returns:

np.ndarray: A boolean array of shape (n_points,) where True indicates a sea point and False indicates a land point.

interpolate(coordinates: InterpolationCoordinates, fvcom_var_name: str, extrapolate_horizontally: bool | None = False, extrapolate_down: bool | None = False, extrapolate_up: bool | None = True, apply_land_sea_mask: bool | None = True, land_sea_mask: ndarray | None = None) → ndarray

Perform interpolation operation for FVCOM data.

The land_sea_mask is only applied when extrapolate is False. If not provided and extrapolate is False, it is automatically generated from the supplied coordinates object through a call to self.generate_land_sea_mask. The argument is included to save on computation time in cases where in interpolate is called multiple times with the same coordinates, e.g., when interpolating multiple variables onto the same grid.

Args:

coordinates (InterpolationCoordinates): Coordinates on the FVCOM grid. fvcom_var_name (str): Name of the FVCOM variable to interpolate. extrapolate_horizontally (Optional[bool]): Whether to allow extrapolation outside the horizontal grid. extrapolate_down (Optional[bool]): Whether to allow extrapolation below the bottom grid. extrapolate_up (Optional[bool]): Whether to allow extrapolation above the surface grid. apply_land_sea_mask (Optional[bool]): Whether to apply the land-sea mask during interpolation. land_sea_mask (Optional[np.ndarray]): Optional land-sea mask to apply during interpolation.

Returns:

np.ndarray: Interpolated variable on the FVCOM grid.

property triangulation_elements_cartesian

Triangulation for FVCOM grid elements in cartesian coordinates.

property triangulation_elements_geographic

Triangulation for FVCOM grid elements in geographic coordinates.

property triangulation_nodes_cartesian

Triangulation for FVCOM grid nodes in cartesian coordinates.

property triangulation_nodes_geographic

Triangulation for FVCOM grid nodes in geographic coordinates.

class pyfvcom2.interpolation.InterpolationCoordinates(dates: ndarray, x3: ndarray, x2: ndarray, x1: ndarray, horizontal_coordinate_system: str, vertical_coordinate_system: str)

Bases: object

property dates

property horizontal_coordinate_system

property vertical_coordinate_system

property x1

property x2

property x3

class pyfvcom2.interpolation.Interpolator

Bases: ABC

Abstract base class for interpolation operations.

abstractmethod interpolate(coordinates: InterpolationCoordinates, fvcom_var_name: str) → ndarray

Perform interpolation operation.

This method must be implemented by subclasses to define the specific interpolation behavior.

Args:

coordinates (InterpolationCoordinates): Coordinates on the FVCOM grid. fvcom_var_name (str): Name of the FVCOM variable to interpolate.

class pyfvcom2.interpolation.TPXOInterpolator(harmonics_data: HarmonicsData, interp_method: str = 'linear')

Bases: Interpolator

TPXO tidal harmonics interpolator.

Interpolates TPXO tidal harmonic amplitudes and phases from the regular TPXO grid onto target positions (e.g., FVCOM open boundary nodes or elements).

Phase interpolation is handled by decomposing amplitude/phase into two cartesian components before interpolation, then converting back. This avoids artifacts from the 360-to-0 degree phase wrapping discontinuity.

Longitude convention mismatches between the TPXO grid (often 0-360) and the target positions (which may use -180 to 180) are detected and corrected automatically.

Args:

harmonics_data: Pre-loaded harmonics data from a TPXOHarmonicsReader

or TPXOComplexHarmonicsReader.

interp_method: Interpolation method passed to scipy’s

RegularGridInterpolator. Defaults to ‘linear’.

interpolate(coordinates: InterpolationCoordinates, fvcom_var_name: str = None) → HarmonicsData

Interpolate TPXO harmonics onto target positions.

Args:

coordinates: Target positions for interpolation. Uses x1 (longitude)

and x2 (latitude).

fvcom_var_name: Not used for TPXO interpolation. Included for

compatibility with the Interpolator interface.

Returns:

HarmonicsData with amplitudes and phases interpolated to the target positions, each shaped (n_points, n_constituents).