advection

Routines for advecting ice parcels using velocity grids

Source code

General Attributes and Methods

class pointAdvection.advection(**kwargs)

Data class for advecting ice parcels using velocity estimates

Attributes:

x: np.ndarray

x-coordinates

y: np.ndarray

y-coordinates

t: np.ndarray

time coordinates

x0: np.ndarray or NoneType, default None

Final x-coordinate after advection

y0: np.ndarray or NoneType, default None

Final y-coordinate after advection

t0: np.ndarray or float, default 0.0

Ending time for advection

velocity: obj

pointCollection object of velocity fields Can be type grid or mesh

vel_mean: obj

pointCollection object of mean velocity field

streak: dict

path traversed during advection (set kwarg ‘streak’ to true

in translate methods to enable)

filename: str

input filename of velocity file

integrator: str

Advection function

• 'euler'

• 'RK4'

• 'RKF45'

method: str, default ‘linear’

Interpolation method for velocities

• 'bilinear': quick bilinear interpolation

• 'spline': scipy bivariate spline interpolation

• 'linear', 'nearest': scipy regular grid interpolations

• 'linearND', 'nearestND': scipy unstructured N-dimensional interpolations

interpolant: obj

Interpolation function for velocity fields

time_units: str, default ‘years’

Temporal units for advection

fill_value: float or NoneType, default np.nan

invalid value for output data

case_insensitive_filename(filename: str | Path | BytesIO)

Searches a directory for a filename without case dependence

Parameters:

filename: str, pathlib.Path, or io.BytesIO

input filename

from_geotiff(filename: str | Path | BytesIO, **kwargs)

Read geotiff velocity file and extract x and y velocities

Parameters:

filename: str or pathlib.Path

geotiff velocity file

bounds: list or NoneType, default None

boundaries to read: [[xmin, xmax], [ymin, ymax]]

If not specified, can read around input points

buffer: float or NoneType, default 5e4

Buffer around input points for extracting velocity fields

scale: float, default None

scaling factor for converting velocities to common units

from_nc(filename: str | IOBase, field_mapping: dict = {'U': 'VX', 'V': 'VY'}, group: str | None = None, bounds: list | ndarray | None = None, buffer: float | None = 50000.0, scale: float = 3.168808781402895e-08, **kwargs)

Read netCDF4 velocity file and extract x and y velocities

Parameters:

filename: str

netCDF4 velocity file

field_mapping: dict, default {‘U’:’VX’, ‘V’:’VY’}

mapping between netCDF4 and output field variables

group: str or NoneType, default None

netCDF4 group to extract variables

bounds: list or NoneType, default None

boundaries to read: [[xmin, xmax], [ymin, ymax]]

If not specified, can read around input points

buffer: float or NoneType, default 5e4

Buffer around input points for extracting velocity fields

scale: float, default None

scaling factor for converting velocities to common units

from_dict(D_dict: dict, **kwargs)

Create an advection object from an input dictionary

Parameters:

D_dict: dict

Dictionary of advection grid variables

bounds: list or NoneType, default None

boundaries to read: [[xmin, xmax], [ymin, ymax]]

If not specified, can read around input points

buffer: float or NoneType, default None

Buffer around input points for extracting velocity fields

scale: float, default None

scaling factor for converting velocities to common units

from_list(D_list: list, **kwargs)

Build a data object from a list of other data objects

Parameters:

D_list: list

pointCollection grid objects

sort: bool, default False

sort the list of data objects before merging

bounds: list or NoneType, default None

boundaries to read: [[xmin, xmax], [ymin, ymax]]

If not specified, can read around input points

buffer: float or NoneType, default None

Buffer around input points for extracting velocity fields

scale: float or NoneType, default None

scaling factor for converting velocities common units

calc_vel_mean(velocity=None, w_smooth=None)

Calculate a mean velocity field

Parameters:

velocity: pc.grid.data, optional

If specified, the mean velocity will be calculated from this, otherwise self.velocity will be used

w_smoothfloat, optional

If specified, gaps in the velocity field will be filed with a Gaussian smoothing of this width. The default is None.

Returns:

pointCollection.grid.data.

error-weighted mean velocity.

fill_velocity_gaps(velocity=None, annual=True, w_smooth=None, vel_mean=None)

Fill in gaps in the velocity field.

Parameters:

velocitypointCollection.grid.data, optional

if specified, mean velocity field will be calculated from this field, otherwise, self.velocity will be used

annualBoolean, optional

If True, will attempt to fill velocity gaps with the average of the previous and next year’s value.

w_smoothfloat, optional

If specified, gaps in the velocity field will be filed with a Gaussian smoothing of this width. The default is None.

vel_meanpointCollection.grid.data, optional

If specified, this will be used as the mean velocity estimate, otherwise will be calculated from the velocity field

Returns:

None.

xy1_interpolator(bounds=None, t_range=None, t_step=None, blocksize=100, advection_time_step=0.25, report_progress=False)

Make interpolation objects for the final position of parcels.

Parameters:

boundsiterable of iterables, optional

x and y bounds of the region to be interpolated. If None, the bounds of the velocity data are used. The default is None.

t_rangeiterable of floats, optional

time bounds of the region to be interpolated, in seconds relative to the epoch. If None, the time bounds of the velocity data is used. The default is None.

t_stepfloat, optional

time step, in time_units. If None, the time values in the velocity data are used.. The default is None.

advection_time_stepfloat, optional

reference time step for the advection object to use. The default is 0.25 (years)

blocksize: int, optional

grid will be divided into blocks of this size, or run all at once if None

Returns:

grid_objpc.grid.data

grid object with fields x1 and y1 containing positions at time t for objects starting at (x, y) at the epoch.

xy0_interpolator(bounds=None, t_range=None, t_step=None, advection_time_step=10, blocksize=100)

Build interpolation objects from initial to final positions

Parameters:

boundsiterable, optional

bounds of the interpolation domain. Can be specified as two iterables (x, y) or three (x, y, t). The default is None.

t_rangeiterable, optional

time range for the interpolation, in velocity time units (seconds relative

to epoch). If not specified, the time range of self.velocity will be used. The default is None.

t_stepfloat, optional

The time step for the interpolation, in time_units. If None, the time values in the velocity object will be used. The default is None.

advection_time_stepfloat, optional

The time step to use in parcel tracking, in days. The default is 5.

Returns

——-

grid_objpc.grid.data

grid object with fields x0 and y0 containing positions at the epoch for parcels starting at x, y, t

translate_parcel(**kwargs)

Translates a parcel between two times using an advection function

Parameters:

integrator: str

Advection function

• 'euler'

• 'RK4'

• 'RKF45'

method: str

Interpolation method for velocities

• 'bilinear': quick bilinear interpolation

• 'spline': scipy bivariate spline interpolation

• 'linear', 'nearest': scipy regular grid interpolations

• 'linearND', 'nearestND': scipy unstructured N-dimensional interpolations

step: int or float, default 1

Temporal step size for advection

N: int or NoneType, default None

Number of integration steps

Default is determined based on the temporal step size

t0: float, default 0.0

Ending time for advection

euler(**kwargs)

Advects parcels using an Explicit Euler integration

Parameters:

N: int, default 1

Number of integration steps

RK4(**kwargs)

Advects parcels using a fourth-order Runge-Kutta integration

Parameters:

N: int, default 1

Number of integration steps

RKF45(**kwargs)

Advects parcels using a Runge-Kutta-Fehlberg 4(5) integration

Parameters:

N: int, default 1

Number of integration steps

RFK45_velocities(xi: ndarray, yi: ndarray, dt: ndarray, **kwargs)

Calculates X and Y velocities for Runge-Kutta-Fehlberg 4(5) method

Parameters:

xi: np.ndarray

x-coordinates

yi: np.ndarray

y-coordinates

dt: np.ndarray

integration time step size

t: np.ndarray or NoneType, default None

time coordinates

buffered_bounds(buffer=50000.0)

Calculates the bounding box including a buffer distance

property distance

Calculates displacement between the start and end coordinates

Returns:

dist: np.ndarray

Eulerian distance between start and end points

inside_polygon(x: ndarray, y: ndarray, threshold: float = 0.01)

Indicates whether a specified 2D point is inside a specified 2D polygon

Parameters:

x: np.ndarray

x-coordinates to query

y: np.ndarray

y-coordinates to query

threshold: float, default 0.01

Minimum angle for checking if inside polygon

Returns:

flag: bool

Flag specifying if point is within polygon

• True for points within polygon,

• False for points outside polygon

interpolate(**kwargs)

Wrapper function for calling interpolation functions

Returns:

U: np.ndarray

Velocity in x-direction

V: np.ndarray

Velocity in y-direction

bilinear_interpolation(**kwargs)

Bilinearly interpolate U and V velocities to coordinates

Parameters:

x: np.ndarray or NoneType, default None

x-coordinates

y: np.ndarray or NoneType, default None

y-coordinates

fill_value: float, default np.nan

Invalid value

Returns:

U: np.ndarray

Velocity in x-direction

V: np.ndarray

Velocity in y-direction

spline_interpolation(**kwargs)

Interpolate U and V velocities to coordinates using biharmonic splines

Parameters:

x: np.ndarray or NoneType, default None

x-coordinates

y: np.ndarray or NoneType, default None

y-coordinates

kx: int, default 1

degrees of the bivariate spline in x-direction

ky: int, default 1

degrees of the bivariate spline in y-direction

fill_value: float, default np.nan

Invalid value

Returns:

U: np.ndarray

Velocity in x-direction

V: np.ndarray

Velocity in y-direction

regular_grid_interpolation(**kwargs)

Interpolate U and V velocities to coordinates using regular grid interpolation

Can use time-variable U and V velocities

Parameters:

x: np.ndarray or NoneType, default None

x-coordinates

y: np.ndarray or NoneType, default None

y-coordinates

t: np.ndarray or NoneType, default None

time coordinates

method: str

Method of regular grid interpolation

• 'nearest'

• 'linear'

fill_value: float, default np.nan

Invalid value

Returns:

U: np.ndarray

Velocity in x-direction

V: np.ndarray

Velocity in y-direction

unstructured_interpolation(**kwargs)

Interpolate unstructured U and V velocities to coordinates using N-dimensional interpolation functions

Parameters:

x: np.ndarray or NoneType, default None

x-coordinates

y: np.ndarray or NoneType, default None

y-coordinates

t: np.ndarray or NoneType, default None

time coordinates

method: str

Method of unstructured interpolation

• 'nearestND'

• 'linearND'

rescale: bool, default False

Rescale points to unit cube before performing interpolation

tree_options: dict or NoneType, default None

Options passed to underlying KDTree for nearestND

fill_value: float, default np.nan

Invalid value

Returns:

U: np.ndarray

Velocity in x-direction

V: np.ndarray

Velocity in y-direction

find_valid_triangulation(x: ndarray, y: ndarray)

Attempt to find a valid Delaunay triangulation for coordinates

• Attempt 1: Qt Qbb Qc Qz

• Attempt 2: Qt Qc QbB

• Attempt 3: QJ QbB

Parameters:

x: np.ndarray

x-coordinates for mesh

y: np.ndarray

y-coordinates for mesh

inside_simplex(x: ndarray, y: ndarray)

Indicates whether a specified 2D point is inside the convex hull of a mesh

Parameters:

x: np.ndarray

x-coordinates to query

y: np.ndarray

y-coordinates to query

Returns:

flag: bool

Flag specifying if point is within convex hull

• True for points within convex hull

• False for points outside convex hull

triangle_maximum_angle(Ax: ndarray, Ay: ndarray, Bx: ndarray, By: ndarray, Cx: ndarray, Cy: ndarray)

Calculates the maximum angles within triangles with vertices A, B and C

Parameters:

Ax: np.ndarray

x-coordinates of A vertices

Ay: np.ndarray

y-coordinates of A vertices

Bx: np.ndarray

x-coordinates of B vertices

By: np.ndarray

y-coordinates of B vertices

Cx: np.ndarray

x-coordinates of C vertices

Cy: np.ndarray

y-coordinates of C vertices

imshow(band=None, ax=None, imtype='speed', xy_scale=1.0, **kwargs)

Create plot of velocity magnitude or divergence

Parameters:

band: int or NoneType, default None

band of velocity grid to show

ax: obj or NoneType, default None

matplotlib figure axis

imtype: str, default ‘speed’

image type to plot

• 'speed': velocity magnitude

• 'divergence': flow divergence

xy_scale: float, default 1.0

Scaling factor for converting horizontal coordinates

**kwargs: dict

Keyword arguments for plt.imshow

Returns:

im: obj

matplotlib AxesImage object

triplot(ax=None, **kwargs)

Create plot of unstructured triangular mesh

Parameters:

ax: obj or NoneType, default None

matplotlib figure axis

**kwargs: dict

Keyword arguments for plt.triplot

Returns:

im: obj

matplotlib AxesImage object

tricontourf(band=None, ax=None, **kwargs)

Create plot of velocity magnitude for unstructured meshes

Parameters:

band: int or NoneType, default None

band of velocity mesh to show

ax: obj or NoneType, default None

matplotlib figure axis

**kwargs: dict

Keyword arguments for plt.tricontourf

Returns:

im: obj

matplotlib AxesImage object

streamplot(band=None, ax=None, xy_scale=1.0, density=[0.5, 0.5], color='0.3', **kwargs)

Create stream plot of velocity vectors

Parameters:

band: int or NoneType, default None

band of velocity grid to show

ax: obj or NoneType, default None

matplotlib figure axis

xy_scale: float, default 1.0

Scaling factor for converting horizontal coordinates

density: float, default [0.5, 0.5]

Closeness of streamlines

color: str, default ‘0.3’

Streamline color

**kwargs: dict

Keyword arguments for plt.streamplot

Returns:

sp: obj

matplotlib StreamplotSet object

copy()

Returns a copy of the object