API Reference

Filter Class

class gcm_filters.Filter(filter_scale: float, dx_min: float, filter_shape: ~gcm_filters.filter.FilterShape = FilterShape.GAUSSIAN, transition_width: float = 3.141592653589793, ndim: int = 2, n_steps: int = 0, grid_type: ~gcm_filters.kernels.GridType = GridType.REGULAR, grid_vars: dict = <factory>)

A class for applying diffusion-based smoothing filters to gridded data.

Parameters:

• filter_scale (float) – The filter scale, which has different meaning depending on filter shape

• dx_min (float) – The smallest grid spacing. Should have same units as filter_scale

• n_steps (int, optional) – Number of total steps in the filter n_steps == 0 means the number of steps is chosen automatically

• filter_shape (FilterShape) –

  • FilterShape.GAUSSIAN: The target filter has shape \(e^{-(k filter_scale)^2/24}\)

  • FilterShape.TAPER: The target filter has target grid scale Lf. Smaller scales are zeroed out. Scales larger than pi * filter_scale / 2 are left as-is. In between is a smooth transition.

• transition_width (float, optional) – Width of the transition region in the “Taper” filter. This is a nondimensional parameter. Theoretical minimum is 1; not recommended.

• ndim (int, optional) – Laplacian is applied on a grid of dimension ndim

• grid_type (GridType) – what sort of grid we are dealing with

• grid_vars (dict) – dictionary of extra parameters used to initialize the grid Laplacian

filter_spec

Type:

FilterSpec

Methods

apply(ds, dims)	Filter an xarray.DataArray or xarray.Dataset with a scalar Laplacian across the dimensions specified by dims.
apply_to_vector(ufield, vfield, dims)	Filter a vector field with vector Laplacian across the dimensions specified by dims.
plot_shape([ax])	Plot the shape of the target filter and approximation.

apply(ds, dims)

Filter an xarray.DataArray or xarray.Dataset with a scalar Laplacian across the dimensions specified by dims.

Parameters:

• ds (xarray.DataArray or xarray.Dataset) – The data to be filtered. If Dataset, filter will be applied to all data variables.

• dims (sequence of str) –

  The names of the dimensions over which to apply the filter. Usually this is two spatial dimensions, e.g. ('lat', 'lon') or ('y', 'x').

  Warning

  The dimension order matters! Since some filters deal with anisotropic grids, the latitude dimension must appear first in order to obtain the correct result.

apply_to_vector(ufield, vfield, dims)

Filter a vector field with vector Laplacian across the dimensions specified by dims.

Parameters:

• ufield (xarray.DataArray) – The zonal component of the data to be filtered.

• vfield (xarray.DataArray) – The meridional component of the data to be filtered.

• dims (sequence of str) –

  The names of the dimensions over which to apply the filter. Usually this is two spatial dimensions, e.g. ('lat', 'lon') or ('y', 'x').

  Warning

  The dimension order matters! Since some filters deal with anisotropic grids, the latitude dimension must appear first in order to obtain the correct result.

plot_shape(ax=None)

Plot the shape of the target filter and approximation.

Kernels

Core smoothing routines that operate on 2D arrays.

class gcm_filters.kernels.AreaWeightedMixin(area: ndarray)

Bases: ABC

Mixin to weight and deweight a field by the cell area.

area

Type:

cell area

Methods

finalize
prepare

class gcm_filters.kernels.BaseScalarLaplacian

Bases: ABC

Base class for scalar Laplacians.

Methods

__call__(field)	Call self as a function.
required_grid_args()

finalize
prepare

class gcm_filters.kernels.BaseVectorLaplacian

Bases: ABC

Base class for vector Laplacians.

Methods

__call__(ufield, vfield)	Call self as a function.
required_grid_args()

finalize
prepare

class gcm_filters.kernels.BgridVectorLaplacian(DXU: ndarray, DYU: ndarray, HUS: ndarray, HUW: ndarray, HTE: ndarray, HTN: ndarray, UAREA: ndarray, TAREA: ndarray)

Bases: BaseVectorLaplacian

̵Vector Laplacian on B-Grid. Implemented for viscosity operators on B-grids based on POP code. Assumes periodic boundary conditions.

DXU

Type:

x-spacing centered at U points

DYU

Type:

y-spacing centered at U points

HUS

Type:

cell widths on south side of U cell

HUW

Type:

cell widths on west side of U cell

HTE

Type:

cell widths on east side of T cell

HTN

Type:

cell widths on north side of T cell

UAREA

Type:

U-cell area

TAREA

Type:

T-cell area

Methods

__call__(ufield, vfield)	Call self as a function.
required_grid_args()

finalize
prepare

class gcm_filters.kernels.CgridVectorLaplacian(wet_mask_t: ndarray, wet_mask_q: ndarray, dxT: ndarray, dyT: ndarray, dxCu: ndarray, dyCu: ndarray, dxCv: ndarray, dyCv: ndarray, dxBu: ndarray, dyBu: ndarray, area_u: ndarray, area_v: ndarray, kappa_iso: ndarray, kappa_aniso: ndarray)

Bases: BaseVectorLaplacian

̵Vector Laplacian on C-Grid. Follows The implementation for viscosity operators on C-grids suggested by Griffies and Hallberg, 2000.

wet_mask_t

Type:

Mask array for t points, 1 for ocean, 0 for land

wet_mask_q

Type:

Mask array for q (vorticity) points, 1 for ocean, 0 for land

dxT

Type:

x-spacing centered at t points

dyT

Type:

y-spacing centered at t points

dxCu

Type:

x-spacing centered at u points

dyCu

Type:

y-spacing centered at u points

dxCv

Type:

x-spacing centered at v points

dyCv

Type:

y-spacing centered at v points

dxBu

Type:

x-spacing centered at q points

dyBu

Type:

y-spacing centered at q points

area_u

Type:

U-cell area

area_v

Type:

V-cell area

kappa_iso

Type:

isotropic viscosity

kappa_aniso

Type:

additive anisotropic viscosity aligned with x-direction

Methods

__call__(ufield, vfield)	Call self as a function.
required_grid_args()

finalize
prepare

class gcm_filters.kernels.GridType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

class gcm_filters.kernels.IrregularLaplacianWithLandMask(wet_mask: ndarray, dxw: ndarray, dyw: ndarray, dxs: ndarray, dys: ndarray, area: ndarray, kappa_w: ndarray, kappa_s: ndarray)

Bases: BaseScalarLaplacian

Scalar Laplacian for locally orthogonal grids with land mask.

It is possible to vary the filter scale over the domain by introducing a nondimensional “diffusivity” (attributes kappa_w and kappa_s). For reasons given in Grooms et al. (2021) https://doi.org/10.1002/essoar.10506591.1, we require that both kappa_w and kappa_s values must be <= 1 and that at least one of them is set to 1 somewhere in the domain. Otherwise the scale of the filter will not be equal to filter_scale anywhere in the domain.

wet_mask

Type:

Mask array, 1 for ocean, 0 for land

dxw

Type:

x-spacing centered at western cell edge

dyw

Type:

y-spacing centered at western cell edge

dxs

Type:

x-spacing centered at southern cell edge

dys

Type:

y-spacing centered at southern cell edge

area

Type:

cell area

kappa_w

least one place in the domain must have kappa_w = 1 if kappa_s < 1.

Type:

zonal diffusivity centered at western cell edge, values must be <= 1, and at

kappa_s

least one place in the domain must have kappa_s = 1 if kappa_w < 1.

Type:

meridional diffusivity centered at southern cell edge, values must be <= 1, and at

Methods

__call__(field)	Call self as a function.
required_grid_args()

finalize
prepare

class gcm_filters.kernels.MOM5LaplacianT(wet_mask: ndarray, dxt: ndarray, dyt: ndarray, dxu: ndarray, dyu: ndarray, area_t: ndarray)

Bases: BaseScalarLaplacian

Laplacian for MOM5 (tracer points). MOM5 uses a Northeast convention B-grid, where velocity point U(i,j) is NE of tracer point T(i,j). .. attribute:: For information on MOM5 discretization see

type:

https://mom-ocean.github.io/assets/pdfs/MOM5_manual.pdf

wet_mask

Type:

Mask array, 1 for ocean, 0 for land

dxt

Type:

width in x of T-cell, model diagnostic dxt

dyt

Type:

height in y of T-cell, model diagnostic dyt

dxu

Type:

width in x of U-cell, model diagnostic dxu

dyu

Type:

height in y of U-cell, model diagnostic dyu

area_t

Type:

area of T-cell, dxt*dyt

Methods

__call__(field)	Call self as a function.
required_grid_args()

finalize
prepare

class gcm_filters.kernels.MOM5LaplacianU(wet_mask: ndarray, dxt: ndarray, dyt: ndarray, dxu: ndarray, dyu: ndarray, area_u: ndarray)

Bases: BaseScalarLaplacian

Laplacian for MOM5 (velocity points). MOM5 uses a Northeast convention B-grid, where velocity point U(i,j) is NE of tracer point T(i,j). For information on MOM5 discretization see: https://mom-ocean.github.io/assets/pdfs/MOM5_manual.pdf .. attribute:: wet_mask

type:

Mask array, 1 for ocean, 0 for land

dxt

Type:

width in x of T-cell, model diagnostic dxt

dyt

Type:

height in y of T-cell, model diagnostic dyt

dxu

Type:

width in x of U-cell, model diagnostic dxu

dyu

Type:

height in y of U-cell, model diagnostic dyu

area_u

Type:

area of U-cell, dxu*dyu

Methods

__call__(field)	Call self as a function.
required_grid_args()

finalize
prepare

class gcm_filters.kernels.POPTripolarLaplacianTpoint(wet_mask: ndarray, dxe: ndarray, dye: ndarray, dxn: ndarray, dyn: ndarray, tarea: ndarray)

Bases: BaseScalarLaplacian

̵Scalar Laplacian for locally orthogonal grid with land mask and tripole boundary condition, as for example used in the global POP configuration. This Laplacian works for scalar fields located at T-points. .. attribute:: wet_mask

type:

Mask array, 1 for ocean, 0 for land; can be obtained via xr.where(KMT>0, 1, 0)

dxe

Type:

x-spacing centered at eastern T-cell edge, provided by POP model diagnostic HUS(nlat, nlon)

dye

Type:

y-spacing centered at eastern T-cell edge, provided by POP model diagnostic HTE(nlat, nlon)

dxn

Type:

x-spacing centered at northern T-cell edge, provided by POP model diagnostic HTN(nlat, nlon)

dyn

Type:

y-spacing centered at northern T-cell edge, provided by POP model diagnostic HUW(nlat, nlon)

tarea

Type:

cell area, provided by POP model diagnostic TAREA(nlat, nlon)

Methods

__call__(field)	Call self as a function.
required_grid_args()

finalize
prepare

class gcm_filters.kernels.RegularLaplacian

Bases: BaseScalarLaplacian

̵Scalar Laplacian for regularly spaced Cartesian grids.

Methods

__call__(field)	Call self as a function.
required_grid_args()

finalize
prepare

class gcm_filters.kernels.RegularLaplacianWithArea(area: ndarray)

Bases: AreaWeightedMixin, RegularLaplacian

̵Scalar Laplacian operating on a locally orthogonal grid in three steps:

1. prepare(): Field is multiplied by the cell area. This corresponds to transforming the field from the original locally orthogonal grid to a regularly spaced Cartesian grid with dx = dy = 1.

2. __call__(): Laplacian acts on regular Cartesian grid.

3. finalize(): Diffused field is divided by the cell area of the original grid. This corresponds to transforming the field from the regular Cartesian grid back to the original grid.

area

Type:

cell area

Methods

__call__(field)	Call self as a function.
required_grid_args()

finalize
prepare

class gcm_filters.kernels.RegularLaplacianWithLandMask(wet_mask: ndarray)

Bases: BaseScalarLaplacian

̵Scalar Laplacian for regularly spaced Cartesian grids with land mask.

wet_mask

Type:

Mask array, 1 for ocean, 0 for land

Methods

__call__(field)	Call self as a function.
required_grid_args()

finalize
prepare

class gcm_filters.kernels.RegularLaplacianWithLandMaskAndArea(wet_mask: ndarray, area: ndarray)

Bases: AreaWeightedMixin, RegularLaplacianWithLandMask

̵Scalar Laplacian operating on a locally orthogonal grid with land mask in three steps:

1. prepare(): Field is multiplied by the cell area. This corresponds to transforming the field from the original locally orthogonal grid to a regularly spaced Cartesian grid with dx = dy = 1.

2. __call__(): Laplacian acts on regular Cartesian grid.

3. finalize(): Diffused field is divided by the cell area of the original grid. This corresponds to transforming the field from the regular Cartesian grid back to the original grid.

area

Type:

cell area

wet_mask

Type:

Mask array, 1 for ocean, 0 for land

Methods

__call__(field)	Call self as a function.
required_grid_args()

finalize
prepare

class gcm_filters.kernels.TripolarRegularLaplacianTpoint(area: ndarray, wet_mask: ndarray)

Bases: AreaWeightedMixin, BaseScalarLaplacian

Scalar Laplacian operating on a locally orthogonal grid with land mask and a tripole boundary. There are three steps:

1. prepare(): Field is multiplied by the cell area. This corresponds to transforming the field from the original locally orthogonal grid to a regularly spaced Cartesian grid with dx = dy = 1.

2. __call__(): Laplacian acts on regular Cartesian grid.

3. finalize(): Diffused field is divided by the cell area of the original grid. This corresponds to transforming the field from the regular Cartesian grid back to the original grid.

area

Type:

cell area

wet_mask

Type:

Mask array, 1 for ocean, 0 for land

Methods

__call__(field)	Call self as a function.
required_grid_args()

finalize
prepare

gcm_filters.kernels.required_grid_vars(grid_type: GridType)

Utility function for figuring out the required grid variables needed by each grid type.

Parameters:

grid_type (GridType) – The grid type

Returns:

grid_vars – A list of names of required grid variables.

Return type:

list