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

Parameters:

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

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

Perform interpolation operation for CMEMS data.

Parameters:

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

Returns:

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.

Return type:

np.ndarray

class pyfvcom2.interpolation.FVCOMInterpolator(fvcom_reader: FVCOMReader)

Bases: Interpolator

FVCOM interpolator class

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

Nearest-neighbor interpolation
Linear interpolation from a delaunay triangulation
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.

Parameters:: 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.

Parameters:: coordinates (InterpolationCoordinates) – The interpolation coordinates for which to generate the mask.
Returns:: A boolean array of shape (n_points,) where True indicates a sea point and False indicates a land point.
Return type:: np.ndarray

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.

Parameters:

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:

Interpolated variable on the FVCOM grid.

Return type:

np.ndarray

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.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.

Parameters:

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

class pyfvcom2.interpolation.NEMOInterpolator(nemo_reader: NEMOReader, fvcom_to_nemo_var_names: dict | None = None)

Bases: Interpolator

NEMO interpolator for native-grid fields.

Supports scalar 2D and 3D variables on curvilinear geographic grids. NEMO U/V velocities are interpolated from their native staggered grids and rotated onto east/north components before being returned as FVCOM u and v.

Parameters:

nemo_reader – A NEMOReader instance with one or more grid file groups loaded.
fvcom_to_nemo_var_names – Mapping from FVCOM names to NEMO variable names. Defaults to temperature, salinity, sea-surface height and velocity mappings.

interpolate(coordinates: InterpolationCoordinates, fvcom_var_name: str) → ndarray: Interpolate a NEMO variable onto supplied FVCOM coordinates.

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.

Parameters:

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.

Parameters:

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).