API Reference

This page provides detailed documentation for all modules and classes in the implicit_filter package.

Filter Base Class

class implicit_filter.filter.Filter(*initial_data, **kwargs)[source]

Bases: ABC

Abstract base class for filters

abstract compute(n: int, k: float | ndarray, data: ndarray) → ndarray[source]

Compute the filtered data using a specified filter size. Data must be placed on mesh nodes

Parameters:

nint

Order of filter, one is recommended

kfloat | np.ndarray

Wavelength of the filter. Float can be passed to be applied for entire mesh or array with scales for each node. Size of the array must match the size of the input data

datanp.ndarray

NumPy array containing data to be filtered.

Returns:

np.ndarray

NumPy array with filtered data.

abstract compute_spectra_scalar(n: int, k: Iterable | ndarray, data: ndarray, mask: ndarray | None = None) → ndarray[source]

Computes power spectra for given wavelengths. Data must be placed on mesh nodes

If one want’s to use spatialy varying filter scale, k should be list of numpy arrays with size mathing the input data.

For details refer to https://arxiv.org/abs/2404.07398 Parameters: ———– n : int

Order of filter, one is recommended

kIterable | np.ndarray

List of wavelengths to be filtered.

datanp.ndarray

NumPy array containing data to be filtered.

masknp.ndarray | None

Mask applied to data while computing spectra. True means selected data won’t be used for computing spectra. This mask won’t be used during filtering.

Returns:

np.ndarray:

Array containing power spectra for given wavelengths.

abstract compute_spectra_velocity(n: int, k: Iterable | ndarray, ux: ndarray, vy: ndarray, mask: ndarray | None = None) → ndarray[source]

Computes power spectra for given wavelengths. Data must be placed on mesh nodes

If one want’s to use spatialy varying filter scale, k should be list of numpy arrays with size mathing the input data.

For details refer to https://arxiv.org/abs/2404.07398 Parameters: ———– n : int

Order of filter, one is recommended

kIterable | np.ndarray

List of wavelengths to be filtered.

uxnp.ndarray

NumPy array containing an eastward velocity component to be filtered.

vynp.ndarray

NumPy array containing a northwards velocity component to be filtered.

masknp.ndarray | None

Mask applied to data while computing spectra. True means selected data won’t be used for computing spectra. This mask won’t be used during filtering.

Returns:

np.ndarray:

Array containing power spectra for given wavelengths.

abstract compute_velocity(n: int, k: float | ndarray, ux: ndarray, vy: ndarray) → Tuple[ndarray, ndarray][source]

Compute the filtered velocity data using a specified filter size. Data must be placed on mesh nodes

Parameters:

nint

Order of filter, one is recommended

kfloat | np.ndarray

Wavelength of the filter. Float can be passed to be applied for entire mesh or array with scales for each node. Size of the array must match the size of the input data

uxnp.ndarray

NumPy array containing eastward velocity component to be filtered.

vynp.ndarray

NumPy array containing northwards velocity component to be filtered.

Returns:

Tuple[np.ndarray, np.ndarray]:

Tuple containing NumPy arrays with filtered data ux and uy velocities on mesh nodes.

abstract get_backend() → str[source]

Get the current computational backend.

Returns:

Name of the active backend.

Return type:

str

classmethod load_from_file(file: str)[source]

Instantiate filter from saved state file.

Parameters:

file (str) – Input file path created by save_to_file()

Returns:

Reconstructed filter instance with restored state

Return type:

Filter

save_to_file(file: str)[source]

Persist internal state to NPZ file.

Parameters:

file (str) – Output file path (.npz extension recommended)

abstract set_backend(backend: str)[source]

Set the computational backend for filter operations.

Parameters:

backend (str) – Name of the backend to use (e.g., ‘cpu’, ‘gpu’).

Triangular Mesh Filters

class implicit_filter.triangular_filter.TriangularFilter(*initial_data, **kwargs)[source]

Bases: Filter

A class for filtering data using JAX for generic triangular meshes. Extends the base Filter class.

Attributes:

_elem_areaOptional[jnp.ndarray]

Area of each element in the mesh.

_areaOptional[jnp.ndarray]

Area of each node’s neighborhood in the mesh.

_ne_posOptional[jnp.ndarray]

Connectivity matrix representing neighboring elements for each node.

_ne_numOptional[jnp.ndarray]

Number of neighboring elements for each node.

_dxOptional[jnp.ndarray]

X-component of the derivative of P1 basis functions.

_dyOptional[jnp.ndarray]

Y-component of the derivative of P1 basis functions.

_ssOptional[jnp.ndarray]

Non-zero entries of the sparse matrix.

_iiOptional[jnp.ndarray]

Row indices of non-zero entries.

_jjOptional[jnp.ndarray]

Column indices of non-zero entries.

_n2dint

Total number of nodes in the mesh.

_fullbool

Flag indicating whether to use the full matrix.

_mask_n: Optional[jnp.ndarray]

Mask of valid elements in the mesh. For example it can land mask.

Methods:

compute_velocity(n: int, k: float, ux: np.ndarray, vy: np.ndarray) -> Tuple[np.ndarray, np.ndarray]:

Compute filtered velocity components (u, v) using implicit filtering.

Compute(n: int, k: float, data: np.ndarray) -> np.ndarray:

Compute filtered data using implicit filtering.

Prepare(n2d: int, e2d: int, tri: np.ndarray, xcoord: np.ndarray, ycoord: np.ndarray, meshtype: str,

cartesian: bool, cyclic_length: float, full: bool = False):

Prepare the filter for a specific mesh.

compute(n: int, k: float | ndarray, data: ndarray) → ndarray[source]

Apply filter to scalar field on triangular mesh.

Parameters:

  • n (int) – Filter order (must be positive).

  • k (float | np.ndarray) – Filter wavelength in spatial units. Float can be passed to be applied for entire mesh or array with scales for each node. Size of the array must match the size of the input data

  • data (np.ndarray) – Scalar field values at mesh nodes.

Returns:

Filtered scalar field.

Return type:

np.ndarray

Raises:

ValueError – If filter order n < 1.

compute_spectra_scalar(n: int, k: Iterable | ndarray, data: ndarray, mask: ndarray | None = None) → ndarray[source]

Compute power spectra for scalar field at specified wavelengths.

If one want’s to use spatialy varying filter scale, k should be list of numpy arrays with size mathing the input data.

Parameters:

  • n (int) – Filter order (must be positive).

  • k (Iterable | np.ndarray) – Target wavelengths for spectral analysis.

  • data (np.ndarray) – Scalar field values at mesh nodes.

  • mask (np.ndarray, optional) – Boolean mask where True excludes nodes from spectra computation.

Returns:

Power spectral density at wavelengths [0, k0, k1, …]: [0] : Total variance [1:] : Variance at each wavelength k

Return type:

np.ndarray

compute_spectra_velocity(n: int, k: Iterable | ndarray, ux: ndarray, vy: ndarray, mask: ndarray | None = None) → ndarray[source]

Compute power spectra for velocity field at specified wavelengths.

If one want’s to use spatialy varying filter scale, k should be list of numpy arrays with size mathing the input data.

Parameters:

  • n (int) – Filter order (must be positive).

  • k (Iterable | np.ndarray) – Target wavelengths for spectral analysis.

  • ux (np.ndarray) – Eastward velocity component at mesh nodes.

  • vy (np.ndarray) – Northward velocity component at mesh nodes.

  • mask (np.ndarray, optional) – Boolean mask where True excludes nodes from spectra computation.

Returns:

Kinetic energy spectral density at wavelengths [0, k0, k1, …]: [0] : Total kinetic energy [1:] : Kinetic energy at each wavelength k

Return type:

np.ndarray

Notes

Implements spectral decomposition:

E(k) = ⟨(u - uₖ)² + (v - vₖ)²⟩

where (uₖ, vₖ) is the filtered velocity at wavelength k.

compute_velocity(n: int, k: float | ndarray, ux: ndarray, vy: ndarray) → Tuple[ndarray, ndarray][source]

Apply filter to velocity components on triangular mesh.

Parameters:

  • n (int) – Filter order (must be positive).

  • k (float | np.ndarray) – Filter wavelength in spatial units. Float can be passed to be applied for entire mesh or array with scales for each node. Size of the array must match the size of the input data

  • ux (np.ndarray) – Eastward velocity component at mesh nodes.

  • vy (np.ndarray) – Northward velocity component at mesh nodes.

Returns:

Filtered velocity components (ux_filt, vy_filt).

Return type:

Tuple[np.ndarray, np.ndarray]

Raises:

  • ValueError – If filter order n < 1.

  • SolverNotConvergedError – If linear solver fails to converge.

get_backend() → str[source]

Get current computational backend.

Returns:

Current backend (‘cpu’ or ‘gpu’).

Return type:

str

prepare(n2d: int, e2d: int, tri: ndarray, xcoord: ndarray, ycoord: ndarray, meshtype: str = 'r', cartesian: bool = True, cyclic_length: float = 6.283185307179586, full: bool = False, mask: ndarray | None = None, gpu: bool = False)[source]

Prepare filter for a specific triangular mesh.

Computes mesh topology, geometric properties, and assembles the filter operator matrix. Must be called before any filtering operations.

Parameters:

  • n2d (int) – Number of nodes in the mesh.

  • e2d (int) – Number of elements in the mesh.

  • tri (np.ndarray) – Element connectivity matrix (e2d x 3) of node indices.

  • xcoord (np.ndarray) – X-coordinates of mesh nodes (degrees).

  • ycoord (np.ndarray) – Y-coordinates of mesh nodes (degrees).

  • meshtype (str, optional) – Mesh type coordinate unit: ‘m’ for metric, ‘r’ for radial(degrees).

  • cartesian (bool, optional) – True for Cartesian coordinates, False for spherical.

  • cyclic_length (float, optional) – Cyclic domain length in radians (default: 2π).

  • full (bool, optional) – True to include metric terms in operator (default: False).

  • mask (np.ndarray, optional) – Element mask where True indicates ocean (default: all ocean).

  • gpu (bool, optional) – True to enable GPU acceleration (default: False).

Notes

Coordinates are expected in degrees while cyclic_length is in radians. The mask is converted to nodal representation where True indicates land.

set_backend(backend: str)[source]

Set computational backend for filtering operations.

Parameters:

backend (str) – Desired backend (‘cpu’ or ‘gpu’).

Notes

Configures appropriate sparse linear algebra functions for the backend.

class implicit_filter.fesom_filter.FesomFilter(*initial_data, **kwargs)[source]

Bases: TriangularFilter

Filter implementation specialized for FESOM ocean model meshes.

This class extends the TriangularFilter to work natively with FESOM mesh files and data structures. It provides convenience methods for loading mesh configurations directly from FESOM output files.

Parameters:

parameters. (See TriangularFilter for inherited)

Notes

Supports FESOM mesh files containing either ‘elements’ or ‘face_nodes’ variables to define element connectivity. Automatically handles FESOM’s 1-based indexing conversion to 0-based indexing for Python.

prepare_from_data_array(mesh: DataArray, meshtype: str = 'r', cartesian: bool = False, cyclic_length: float = 6.283185307179586, metric: bool = False, mask: ndarray | None = None, gpu: bool = False)[source]

Configure filter using an xarray Dataset containing FESOM mesh data.

Parameters:

  • mesh (xr.Dataset) – xarray Dataset containing FESOM mesh variables.

  • meshtype (str, optional) – Mesh type coordinate unit: ‘m’ for metric, ‘r’ for radial(degrees).

  • cartesian (bool, optional) – Coordinate system flag (default: False).

  • cyclic_length (float, optional) – Cyclic domain length in radians (default: 2π).

  • metric (bool, optional) – Metric terms inclusion flag (default: False).

  • mask (np.ndarray, optional) – Element land mask (default: None).

  • gpu (bool, optional) – GPU acceleration flag (default: False).

Raises:

RuntimeError – If mesh doesn’t contain recognizable element connectivity data.

Notes

Looks for element connectivity in variables named: - ‘elements’ - ‘face_nodes’ - ‘elem’

prepare_from_file(file: str, meshtype: str = 'r', cartesian: bool = False, cyclic_length: float = 6.283185307179586, metric: bool = False, mask: ndarray | None = None, gpu: bool = False)[source]

Configure filter using a FESOM mesh file.

Parameters:

  • file (str) – Path to FESOM mesh file (NetCDF format).

  • meshtype (str, optional) – Mesh type coordinate unit: ‘m’ for metric, ‘r’ for radial(degrees).

  • cartesian (bool, optional) – True for Cartesian coordinates, False for spherical (default).

  • cyclic_length (float, optional) – Cyclic domain length in radians (default: 2π).

  • metric (bool, optional) – True to include metric terms in operator (default: False).

  • mask (np.ndarray, optional) – Element land mask where True indicates land (default: None).

  • gpu (bool, optional) – True to enable GPU acceleration (default: False).

Notes

This method automatically: 1. Reads the mesh file using xarray 2. Extracts node coordinates and element connectivity 3. Converts FESOM’s 1-based indexing to 0-based indexing 4. Configures the filter using the parent class prepare method

class implicit_filter.icon_filter.IconFilter(*initial_data, **kwargs)[source]

Bases: TriangularFilter

prepare_from_data_array(grid2d: DataArray, full: bool = False, mask: ndarray | bool = False, gpu: bool = False)[source]

Configure filter using an xarray Dataset containing ICON grid data.

Parameters:

  • grid2d (xr.Dataset) – xarray Dataset containing ICON grid variables.

  • full (bool, optional) – Metric terms inclusion flag (default: False).

  • mask (np.ndarray | bool, optional) – Land-sea mask specification: - np.ndarray: Precomputed mask array where true is ocean - True: Auto-detect from ‘cell_sea_land_mask’ - False: All ocean cells (default)

  • gpu (bool, optional) – GPU acceleration flag (default: False).

Raises:

KeyError – If mask=True but ‘cell_sea_land_mask’ not found in dataset.

Notes

  • Vertex coordinates are converted from radians to degrees

  • Element connectivity is expected in ‘vertex_of_cell’ variable

  • Spherical coordinates with cyclic domain are assumed

  • Land-sea mask is transformed from cell-centered to nodal representation

prepare_from_file(grid_file: str, full: bool = False, mask: ndarray | bool = False, gpu: bool = False)[source]

Configure filter using an ICON grid file.

Parameters:

  • grid_file (str) – Path to ICON grid file (NetCDF format).

  • full (bool, optional) – True to include metric terms in operator (default: False).

  • mask (np.ndarray | bool, optional) – Can be: - Precomputed land mask array - True to automatically detect mask from file - False to treat all cells as ocean (default)

  • gpu (bool, optional) – True to enable GPU acceleration (default: False).

Structured Grid Filters

class implicit_filter.latlon_filter.LatLonFilter(*initial_data, **kwargs)[source]

Bases: Filter

Filter implementation for regular latitude-longitude grids.

This class provides implicit filtering capabilities for data on structured lat-lon grids. It supports both Cartesian and spherical coordinate systems with configurable boundary conditions and land-sea masks.

Parameters:

parameters. (See Filter class for inherited)

_e2d

Total number of grid points (nx * ny)

Type:

int

_nx

Number of longitude points

Type:

int

_ny

Number of latitude points

Type:

int

_ss

Non-zero values of sparse filter matrix

Type:

np.ndarray

_ii

Row indices for sparse matrix entries

Type:

np.ndarray

_jj

Column indices for sparse matrix entries

Type:

np.ndarray

_area

Area associated with each grid cell

Type:

np.ndarray

_backend

Computational backend (‘cpu’ or ‘gpu’)

Type:

str

_mask_n

Boolean mask for valid grid points (False indicates land)

Type:

np.ndarray

compute(n: int, k: float | ndarray, data: ndarray) → ndarray[source]

Apply filter to scalar field on lat-lon grid.

Parameters:

  • n (int) – Filter order (must be positive).

  • k (float | np.ndarray) – Filter wavelength in spatial units. Float can be passed to be applied for entire mesh or array with scales for each node. Size of the array must match the size of the input data

  • data (np.ndarray) – Scalar field values on grid (shape: (nx, ny)).

Returns:

Filtered scalar field (shape: (nx, ny)).

Return type:

np.ndarray

Raises:

ValueError – If filter order n < 1.

compute_spectra_scalar(n: int, k: Iterable | ndarray, data: ndarray, mask: ndarray | None = None) → ndarray[source]

Compute power spectra for scalar field at specified wavelengths.

If one want’s to use spatialy varying filter scale, k should be list of numpy arrays with size mathing the input data.

Parameters:

  • n (int) – Filter order (must be positive).

  • k (Iterable | np.ndarray) – Target wavelengths for spectral analysis.

  • data (np.ndarray) – Scalar field values on grid (shape: (nx, ny)).

  • mask (np.ndarray, optional) – Boolean mask where True excludes points from spectra computation.

Returns:

Power spectral density at wavelengths [0, k0, k1, …]: [0] : Total variance [1:] : Variance at each wavelength k

Return type:

np.ndarray

compute_spectra_velocity(n: int, k: Iterable | ndarray, ux: ndarray, vy: ndarray, mask: ndarray | None = None) → ndarray[source]

Compute power spectra for velocity field at specified wavelengths.

If one want’s to use spatialy varying filter scale, k should be list of numpy arrays with size mathing the input data.

Parameters:

  • n (int) – Filter order (must be positive).

  • k (Iterable | np.ndarray) – Target wavelengths for spectral analysis.

  • ux (np.ndarray) – Eastward velocity component (shape: (nx, ny)).

  • vy (np.ndarray) – Northward velocity component (shape: (nx, ny)).

  • mask (np.ndarray, optional) – Boolean mask where True excludes points from spectra computation.

Returns:

Kinetic energy spectral density at wavelengths [0, k0, k1, …]: [0] : Total kinetic energy [1:] : Kinetic energy at each wavelength k

Return type:

np.ndarray

compute_velocity(n: int, k: float | ndarray, ux: ndarray, vy: ndarray) → Tuple[ndarray, ndarray][source]

Apply filter to velocity components on lat-lon grid.

Parameters:

  • n (int) – Filter order (must be positive).

  • k (float | np.ndarray) – Filter wavelength in spatial units. Float can be passed to be applied for entire mesh or array with scales for each node. Size of the array must match the size of the input data

  • ux (np.ndarray) – Eastward velocity component (shape: (nx, ny)).

  • vy (np.ndarray) – Northward velocity component (shape: (nx, ny)).

Returns:

Filtered velocity components (ux_filt, vy_filt) each with shape (nx, ny).

Return type:

Tuple[np.ndarray, np.ndarray]

Raises:

ValueError – If filter order n < 1.

get_backend() → str[source]

Get current computational backend.

Returns:

Current backend (‘cpu’ or ‘gpu’).

Return type:

str

prepare(latitude: ndarray, longitude: ndarray, cartesian: bool = False, local: bool = True, cyclic_length: float = 6.283185307179586, mask: ndarray | None = None, gpu: bool = False)[source]

Configure filter for a latitude-longitude grid.

Computes grid topology, geometric properties, and assembles the filter operator matrix. Must be called before any filtering operations.

Parameters:

  • latitude (np.ndarray) – Latitude values in degrees (1D array)

  • longitude (np.ndarray) – Longitude values in degrees (1D array)

  • cartesian (bool, optional) – True for Cartesian coordinates, False for spherical (default)

  • local (bool, optional) – True for 4-point local neighborhood, False for 8-point global (default: True)

  • cyclic_length (float, optional) – Cyclic domain length in radians (default: 2π).

  • mask (np.ndarray, optional) – Land-sea mask where True indicates land (default: all ocean)

  • gpu (bool, optional) – True to enable GPU acceleration (default: False)

Notes

  • Land points are masked using Neumann boundary conditions

set_backend(backend: str)[source]

Set computational backend for filtering operations.

Parameters:

backend (str) – Desired backend (‘cpu’ or ‘gpu’).

Notes

Configures appropriate sparse linear algebra functions for the backend.

class implicit_filter.nemo_filter.NemoFilter(*initial_data, **kwargs)[source]

Bases: LatLonFilter

Filter implementation specialized for NEMO ocean model grids.

This class extends LatLonFilter to handle NEMO’s specific grid characteristics including partial cells, scale factors, and complex boundary representations. It supports different neighborhood configurations for accurate filtering.

Parameters:

parameters. (See LatLonFilter for inherited)

Notes

  • Automatically handles NEMO’s redundant point representation

  • Supports three neighborhood types: ‘full’, ‘west-east’, and ‘local’

  • Accounts for partial cells through 3D scale factors

prepare_from_data_array(ds: DataArray, vl: int, mask: ndarray | bool = True, gpu: bool = False, neighb: str = 'full')[source]

Configure filter using an xarray Dataset containing NEMO grid data.

Parameters:

  • ds (xr.Dataset) – xarray Dataset containing NEMO grid variables.

  • vl (int) – Vertical level index for filter configuration.

  • mask (np.ndarray | bool, optional) – Land-sea mask specification (see prepare_from_file).

  • gpu (bool, optional) – GPU acceleration flag (default: False).

  • neighb (str, optional) – Neighborhood type (see prepare_from_file).

Raises:

NotImplementedError – If unsupported neighborhood type is specified.

Notes

  • Requires standard NEMO grid variables: gphit, e1t, e2t, e1u, e2v, e3u_0, e3v_0, e3t_0

  • The ‘tmask’ variable is used for land-sea masking when auto-detection is enabled

  • Handles North Pole folding in ‘full’ neighborhood configuration

  • Grid metrics are converted from meters to kilometers for consistency

prepare_from_file(file: str, vl: int, mask: ndarray | bool = True, gpu: bool = False, neighb: str = 'full')[source]

Configure filter using a NEMO grid file.

Parameters:

  • file (str) – Path to NEMO grid file (NetCDF format).

  • vl (int) – Vertical level index for which to configure the filter.

  • mask (np.ndarray | bool, optional) – Land-sea mask specification: - np.ndarray: Precomputed mask array - True: Auto-detect from ‘tmask’ variable (default) - False: All ocean cells

  • gpu (bool, optional) – True to enable GPU acceleration (default: False).

  • neighb (str, optional) – Neighborhood type: - ‘full’: Full 4-point neighborhood with North Pole handling - ‘west-east’: Zonal connections only - ‘local’: Standard 4-point neighborhood (default: ‘full’)

Notes

  • Automatically detects and handles NEMO’s redundant grid points

  • Converts grid metrics from meters to kilometers

  • Uses vertical level scale factors for accurate cell volumes

Utility Functions

implicit_filter.convert_to_wavenumbers(dist, dxm)[source]

Converts a given spatial distance to wavenumbers for spectral analysis.

Parameters:

distfloat

The spatial distance for which wavenumbers are to be calculated.

dxmfloat

The mesh resolution, representing the distance between grid points.

Returns:

float

The corresponding wavenumber for the given spatial distance.

Notes:

  • Input parameters dist and dxm must have the same unit.

  • The factor 3.5 is used to make the results comparable with box-type filters.

implicit_filter.transform_mask_from_elements_to_nodes(mask: ndarray, filter: filter) → ndarray[source]

Transform land-sea mask from elements to nodes for triangular meshes.

Parameters:

  • mask (np.ndarray) – Boolean land-sea mask defined on mesh elements (True = land).

  • filter (Filter) – Filter instance (must be TriangularFilter or subclass).

Returns:

Land-sea mask interpolated to mesh nodes (True = land).

Return type:

np.ndarray

Raises:

TypeError – If filter is not a TriangularFilter subclass.

Notes

A node is considered land if any of its connected elements are land. Useful for converting element-based masks to nodal representation.

implicit_filter.transform_mask_from_nodes_to_elements(mask: ndarray, filter: filter) → ndarray[source]

Transform land-sea mask from nodes to elements for triangular meshes.

Parameters:

  • mask (np.ndarray) – Boolean land-sea mask defined on mesh nodes (True = land).

  • filter (Filter) – Filter instance (must be TriangularFilter or subclass).

Returns:

Land-sea mask interpolated to mesh elements (True = land).

Return type:

np.ndarray

Raises:

TypeError – If filter is not a TriangularFilter subclass.

Notes

An element is considered land if any of its nodes are land. Useful for converting nodal masks to element-based representation.

implicit_filter.transform_scalar_to_nodes(data, filter: Filter) → tuple[ndarray, ndarray][source]

Transform scalar field from elements to nodes for triangular meshes.

Parameters:

  • data (np.ndarray) – Scalar field defined on mesh elements.

  • filter (Filter) – Filter instance (must be TriangularFilter or subclass).

Returns:

Scalar field interpolated to mesh nodes.

Return type:

np.ndarray

Raises:

TypeError – If filter is not a TriangularFilter subclass.

Notes

Performs area-weighted averaging to interpolate scalar values from element centers to mesh nodes. Only applicable for unstructured triangular meshes.

implicit_filter.transform_to_T_cells(ux: ndarray, vy: ndarray, filter: Filter) → tuple[ndarray, ndarray][source]

Transform velocity components to T-grid points for NEMO grids.

Parameters:

  • ux (np.ndarray) – Eastward velocity component on U-grid points.

  • vy (np.ndarray) – Northward velocity component on V-grid points.

  • filter (Filter) – Filter instance (must be NemoFilter or subclass).

Returns:

Velocity components interpolated to T-grid points (ux_t, vy_t).

Return type:

tuple[np.ndarray, np.ndarray]

Raises:

TypeError – If filter is not a NemoFilter subclass.

Notes

Specifically designed for NEMO’s Arakawa C-grid: - U-points: located at east-west cell faces - V-points: located at north-south cell faces - T-points: located at cell centers Performs simple averaging to interpolate velocities to cell centers.

implicit_filter.transform_velocity_to_nodes(ux: ndarray, vy: ndarray, filter: Filter) → tuple[ndarray, ndarray][source]

Transform velocity components from elements to nodes for triangular meshes.

Parameters:

  • ux (np.ndarray) – Eastward velocity component defined on mesh elements.

  • vy (np.ndarray) – Northward velocity component defined on mesh elements.

  • filter (Filter) – Filter instance (must be TriangularFilter or subclass).

Returns:

Velocity components interpolated to mesh nodes (ux_nodes, vy_nodes).

Return type:

tuple[np.ndarray, np.ndarray]

Raises:

TypeError – If filter is not a TriangularFilter subclass.

Notes

This function performs area-weighted averaging to interpolate velocity components from element centers to mesh nodes. Only applicable for unstructured triangular meshes.

implicit_filter.transform_velocity_to_nodes(ux: ndarray, vy: ndarray, filter: Filter) → tuple[ndarray, ndarray][source]

Transform velocity components from elements to nodes for triangular meshes.

Parameters:

  • ux (np.ndarray) – Eastward velocity component defined on mesh elements.

  • vy (np.ndarray) – Northward velocity component defined on mesh elements.

  • filter (Filter) – Filter instance (must be TriangularFilter or subclass).

Returns:

Velocity components interpolated to mesh nodes (ux_nodes, vy_nodes).

Return type:

tuple[np.ndarray, np.ndarray]

Raises:

TypeError – If filter is not a TriangularFilter subclass.

Notes

This function performs area-weighted averaging to interpolate velocity components from element centers to mesh nodes. Only applicable for unstructured triangular meshes.

implicit_filter.transform_scalar_to_nodes(data, filter: Filter) → tuple[ndarray, ndarray][source]

Transform scalar field from elements to nodes for triangular meshes.

Parameters:

  • data (np.ndarray) – Scalar field defined on mesh elements.

  • filter (Filter) – Filter instance (must be TriangularFilter or subclass).

Returns:

Scalar field interpolated to mesh nodes.

Return type:

np.ndarray

Raises:

TypeError – If filter is not a TriangularFilter subclass.

Notes

Performs area-weighted averaging to interpolate scalar values from element centers to mesh nodes. Only applicable for unstructured triangular meshes.

implicit_filter.transform_mask_from_elements_to_nodes(mask: ndarray, filter: filter) → ndarray[source]

Transform land-sea mask from elements to nodes for triangular meshes.

Parameters:

  • mask (np.ndarray) – Boolean land-sea mask defined on mesh elements (True = land).

  • filter (Filter) – Filter instance (must be TriangularFilter or subclass).

Returns:

Land-sea mask interpolated to mesh nodes (True = land).

Return type:

np.ndarray

Raises:

TypeError – If filter is not a TriangularFilter subclass.

Notes

A node is considered land if any of its connected elements are land. Useful for converting element-based masks to nodal representation.

implicit_filter.transform_mask_from_nodes_to_elements(mask: ndarray, filter: filter) → ndarray[source]

Transform land-sea mask from nodes to elements for triangular meshes.

Parameters:

  • mask (np.ndarray) – Boolean land-sea mask defined on mesh nodes (True = land).

  • filter (Filter) – Filter instance (must be TriangularFilter or subclass).

Returns:

Land-sea mask interpolated to mesh elements (True = land).

Return type:

np.ndarray

Raises:

TypeError – If filter is not a TriangularFilter subclass.

Notes

An element is considered land if any of its nodes are land. Useful for converting nodal masks to element-based representation.

implicit_filter.transform_to_T_cells(ux: ndarray, vy: ndarray, filter: Filter) → tuple[ndarray, ndarray][source]

Transform velocity components to T-grid points for NEMO grids.

Parameters:

  • ux (np.ndarray) – Eastward velocity component on U-grid points.

  • vy (np.ndarray) – Northward velocity component on V-grid points.

  • filter (Filter) – Filter instance (must be NemoFilter or subclass).

Returns:

Velocity components interpolated to T-grid points (ux_t, vy_t).

Return type:

tuple[np.ndarray, np.ndarray]

Raises:

TypeError – If filter is not a NemoFilter subclass.

Notes

Specifically designed for NEMO’s Arakawa C-grid: - U-points: located at east-west cell faces - V-points: located at north-south cell faces - T-points: located at cell centers Performs simple averaging to interpolate velocities to cell centers.

implicit_filter.convert_to_wavenumbers(dist, dxm)[source]

Converts a given spatial distance to wavenumbers for spectral analysis.

Parameters:

distfloat

The spatial distance for which wavenumbers are to be calculated.

dxmfloat

The mesh resolution, representing the distance between grid points.

Returns:

float

The corresponding wavenumber for the given spatial distance.

Notes:

  • Input parameters dist and dxm must have the same unit.

  • The factor 3.5 is used to make the results comparable with box-type filters.

Submodules