numbacs.utils

Module Contents

numbacs.utils.gradF_stencil_2D(F, i, j, dx, dy)

Stencil for computing the gradient of F, a grid of 2D vectors, at (i, j), with spacing dx and dy. Not boundary safe.

Parameters:

• F (np.ndarray, shape = (nx, ny, 2)) – values of the vector F over grid.

• i (int) – index corresponding to the first dimension.

• j (int) – index corresponding to the second dimension.

• dx (float) – spacing in x-direction.

• dy (float) – spacing in y-direction.

Returns:

• dFxdx (float) – derivative of first component in x-direction.

• dFxdy (float) – derivative of first component in y-direction.

• dFydx (float) – derivative of second component in x-direction.

• dFydy (float) – derivative of second component in y-direction.

numbacs.utils.gradF_aux_stencil_2D(F_aux, i, j, h)

Stencil for computing the gradient of F_aux, a grid of 2D vectors, at (i, j), using the aux grid, with spacing h.

Parameters:

• F_aux (np.ndarray, shape = (nx, ny, n_aux, 2)) – values of the vector F over aux-grid.

• i (int) – index corresponding to the first dimension.

• j (int) – index corresponding to the second dimension.

• h (float) – aux grid spacing.

Returns:

• dFxdx (float) – derivative of first component in x-direction.

• dFxdy (float) – derivative of first component in y-direction.

• dFydx (float) – derivative of second component in x-direction.

• dFydy (float) – derivative of second component in y-direction.

numbacs.utils.gradF_main_stencil_2D(F_aux, i, j, dx, dy)

Stencil for computing the gradient of F_aux, a grid of 2D vectors, at (i, j), using the main grid, with spacing dx, dy. Not boundary safe.

Parameters:

• F_aux (np.ndarray, shape = (nx, ny, 5, 2)) – values of the vector F over aux-grid.

• i (int) – index corresponding to the first dimension.

• j (int) – index corresponding to the second dimension.

• dx (float) – spacing in x-direction.

• dy (float) – spacing in y-direction.

Returns:

• dFxdx (float) – derivative of first component in x-direction.

• dFxdy (float) – derivative of first component in y-direction.

• dFydx (float) – derivative of second component in x-direction.

• dFydy (float) – derivative of second component in y-direction.

numbacs.utils.gradUV_stencil_2D(U, V, i, j, dx, dy)

Stencil for computing the gradient of velocity, defined by U, V, at (i, j), with spacing dx and dy. Not boundary safe.

Parameters:

• U (np.ndarray, shape = (nx, ny)) – velocity in x-direction.

• V (np.ndarray, shape = (nx, ny)) – velocity in y-direction.

• i (int) – index corresponding to the first dimension.

• j (int) – index corresponding to the second dimension.

• dx (float) – spacing in x-direction.

• dy (float) – spacing in y-direction.

Returns:

• dUdx (float) – derivative of x velocity in x-direction.

• dUdy (float) – derivative of x velocity in y-direction.

• dVdx (float) – derivative of y velocity in x-direction.

• dVdy (float) – derivative of y velocity in y-direction.

numbacs.utils.eigvalsh_max_2D(A)

Computes the maximum eigenvalue for a Hermetian 2x2 array A.

Parameters:

A (np.ndarray, shape = (2, 2)) – Hermetian 2x2 array.

Returns:

maximum eigenvalue of A.

Return type:

float

numbacs.utils.inv_2D(A)

Computes the inverse of a 2x2 array A.

Parameters:

A (np.ndarray, shape = (2, 2)) – 2x2 array.

Returns:

inverse of A.

Return type:

np.ndarray, shape = (2, 2)

numbacs.utils.vec_dot_2D(v1, v2)

Vector dot product for 2D vectors.

Parameters:

• v1 (np.ndarray, shape=(2,)) – first vector.

• v2 (np.ndarray, shape=(2,)) – second vector.

Returns:

dot product.

Return type:

float

numbacs.utils.vec_dot_3D(v1, v2)

Vector dot product for 3D vectors.

Parameters:

• v1 (np.ndarray, shape=(3,)) – first vector.

• v2 (np.ndarray, shape=(3,)) – second vector.

Returns:

dot product.

Return type:

float

numbacs.utils.unravel_index(index, shape)

Numba currently does not implement np.unravel_index so we create an implementation here for the specific case where order=’C’ (row-major).

Parameters:

• index (int) – raveled index.

• shape (np.ndarray, shape = (ndims,)) – shape of array used for unraveling index.

Returns:

array containing the unraveled index.

Return type:

np.ndarray

numbacs.utils.ravel_index(inds, shape)

Finds raveled index corresponding to grid index given by inds from array with shape=shape where shape must be a np.ndarray.

Parameters:

• inds (np.ndarray, shape = (ndims,)) – array containing indices to be raveled.

• shape (np.ndarray, shape = (ndims,)) – shape of array used for raveling index.

Returns:

r_ind – raveled index.

Return type:

int

numbacs.utils.finite_diff_2D(f, i, j, h, axis, direction='c')

Compute 2nd order partial finite difference in the array f @ [i,j] along axis=axis and using a directional difference scheme defined by direction.

Parameters:

• f (np.ndarray, shape = (nx,ny)) – array on which finite differencing is performed.

• i (int) – index for axis=0 at which finite differencing is performed.

• j (int) – index for axis=1 at which finite differencing is performed.

• h (float) – spacing in axis direction.

• axis (int) – axis over which finite differencing is performed.

• direction (str, optional) – finite differencing direction, optional values are ‘b’ for backward, ‘c’ for centered, and ‘f’ for forward. The default is ‘c’.

Returns:

df – finite difference value.

Return type:

float

numbacs.utils.finite_diff_ND(f, ind, h, axis, shape, direction=0)

Compute 2nd order partial finite difference in the array f @ [ind] where f is an (n_1*n_2*…*n_ndims) array. Axis=axis determines the axis the finite differencing will be performed along shape is [n1,n2,…,n_ndims]. shape must be a np.array and ‘ij’ indexing is assumed.

Parameters:

• f (np.ndarray, shape = (nx_1*nx_2*...*nx_ndims,)) – flattened array of which finite differencing is performed.

• ind (int) – raveled index at which finite differencing is performed.

• h (float) – spacing in axis direction.

• axis (int) – axis over which finite differencing is performed.

• shape (np.ndarray, shape = (ndims,)) – shape of original array before raveled.

• direction (str, optional) – finite differencing direction, optional values are -1 for backward, 0 for centered, and 1 for forward. The default is 0.

Returns:

df – finite difference value.

Return type:

float

numbacs.utils.finite_diff_2D_2nd(f, i, j, h, axis, direction='c')

Compute 2nd order partial finite difference in the array f @ [i,j] along axis=axis and using a directional difference scheme defined by direction for the second derivative. axis=2 is for the mixed partial finite difference.

numbacs.utils.curl_vel(u, v, dx, dy)

Compute curl of vector field defined by u and v.

Parameters:

• u (np.ndarray, shape = (nx,ny)) – array containing x component of vector field.

• v (np.ndarray, shape = (nx,ny)) – array containing y component of vector field.

• dx (float) – spacing in grid in x-direction.

• dy (float) – spacing in grid in y-direction.

Returns:

curl – array containing values of curl of vector field defined by u and v.

Return type:

np.ndarray, shape = (nx,ny)

numbacs.utils.curl_vel_tspan(u, v, dx, dy)

Compute curl of vector field defined by u and v over some timespan.

Parameters:

• u (np.ndarray, shape = (nt,nx,ny)) – array containing x component of vector field.

• v (np.ndarray, shape = (nt,nx,ny)) – array containing y component of vector field.

• dx (float) – spacing in grid in x-direction.

• dy (float) – spacing in grid in y-direction.

Returns:

curl – array containing values of curl of vector field defined by u and v.

Return type:

np.ndarray, shape = (nt,nx,ny)

numbacs.utils.curl_func(fnc, x, y, h=0.001)

Compute curl over x,y of vector field defined by fnc.

Parameters:

• fnc (jit-callable) – callable containing returing x and y components of vector field.

• x (np.ndarray, shape = (nx,)) – array containing x-values.

• y (np.ndarray, shape = (ny,)) – array containing y-values.

• h (float, optional) – spacing used in finite differencing. The default is 1e-3.

Returns:

curlf – array containing values of curl of f.

Return type:

np.ndarray, shape = (nx,ny)

numbacs.utils.curl_func_tspan(fnc, t, x, y, h=0.001)

Compute curl over x,y of vector field defined by func over times t.

Parameters:

• fnc (jit-callable) – callable containing returing x and y components of vector field.

• x (np.ndarray, shape = (nx,)) – array containing x-values.

• y (np.ndarray, shape = (ny,)) – array containing y-values.

• h (float, optional) – spacing used in finite differencing. The default is 1e-3.

Returns:

curlf – array containing values of curl of f.

Return type:

np.ndarray, shape = (nx,ny)

numbacs.utils.composite_simpsons(f, h)

Composite Simpson’s 1/3 rule to compute integral of f between endpoitns of pts with regular spacing given by h.

Parameters:

• f (np.ndarray, shape = (n+1,)) – values of f at regularly spaced points.

• h (float) – value of spacing between points at which f was evaluated.

Returns:

val – value of integral.

Return type:

float

numbacs.utils.composite_simpsons_38_irregular(f, h)

Composite Simpson’s 3/8 rule to compute integral of f between endpoitns of pts with irregular spacing given by h which is an np.ndarray.

Parameters:

• f (np.ndarray, shape = (n+1,)) – values of f at irregularly spaced points.

• h (np.ndarray, shape = (n,)) – values of spacing between points at which f was evaluated.

Returns:

val – value of integral.

Return type:

float

numbacs.utils.dist_2d(p1, p2)

Compute 2D Euclidean distance between p1 and p2.

Parameters:

• p1 (np,ndarry, shape = (2,)) – point 1.

• p2 (np,ndarry, shape = (2,)) – point 2.

Returns:

distance between p1 and p2.

Return type:

float

numbacs.utils.dist_tol(point, arr, tol)

Check if pt is within tolerance of any point in arr.

Parameters:

• point (np.ndarray, shape = (2,)) – point.

• arr (np.ndarray, shape = (n,2)) – array containing points.

• tol (float) – tolerance used for checking distance.

Returns:

near – truth value determining if point is within tol of any point in arr.

Return type:

boolean

numbacs.utils.shoelace(polygon)

Compute area of simple polygon using shoelace algorithm.

Parameters:

polygon (np.ndarray, shape = (n,2)) – array containing vertices of polygon, first and last vertex should be the same.

Returns:

area – area of polygon.

Return type:

float

numbacs.utils.max_in_radius(arr, r, dx, dy, n=-1, min_val=0.0)

Finds n local maxima values in arr such that each max is a local maximum within radius r where spacing in arr is given by dx,dy. If all local maxima are desired, set n = -1. Should pass a copy of arr to the function to avoid orginial arr being overwritten (i.e. pass in arr.copy()).

Parameters:

• arr (np.ndarray, shape = (nx,ny)) – array in which local maxima are to be found.

• r (float) – radius in which points will be discared after a maximum is found at the center.

• dx (float) – gird spacing in x-direction.

• dy (float) – grid spacing in y-direction.

• n (int, optional) – number of maxima to return, -1 returns all. The default is -1.

• min_val (float, optional) – miniumum value allowed for local maxima. The default is 0.0.

Returns:

• max_vals (np.ndarray, shape = (k,) where k number of maxima found) – maxima values in radius.

• max_inds (np.ndarray, shape = (k,) where k number of maxima found) – indices corresponding to max_vals.

numbacs.utils.gen_circ(r, c, n, xlims=None, ylims=None)

Generate n points on a circle with radius r and center c.

Parameters:

• r (float) – radius of circle.

• c (np.ndarray, shape = (2,)) – center of circle.

• n (int) – number of points on circle.

• xlims (tuple, optional) – boundary in x-direction, points outside of this boundary will not be returned. The default is None.

• ylims (tuple, optional) – boundary in y-direction, points outside of this boundary will not be returned. The default is None.

Returns:

pts – points on the circle.

Return type:

np.ndarray, shape = (n,2)

numbacs.utils.gen_filled_circ(r, n, alpha=3.0, c=np.array([0.0, 0.0]), xlims=None, ylims=None)

Generate points filling a circle with radius r and center c. Uses the sunflower seed arangement.

Parameters:

• r (float) – radius of circle.

• n (int) – number of points to fill the circle.

• alpha (float, optional) – parameter determining how smooth the boundary is. The default is 3.0.

• c (np.ndarray, shape = (2,), optional) – center of the circle. The default is np.array([0.0,0.0]).

• xlims (tuple, optional) – boundary in x-direction, points outside of this boundary will not be returned. The default is None.

• ylims (tuple, optional) – boundary in y-direction, points outside of this boundary will not be returned. The default is None.

Returns:

pts – array containing points which fill the circle.

Return type:

np.ndarray, shape = (n,2)

numbacs.utils.gen_filled_circ_radius(r, n, alpha=3.0, c=np.array([0.0, 0.0]), xlims=None, ylims=None)

Generate points filling a circle with radius r and center c. Uses the sunflower seed arangement. Also returns radius of each point from center c.

Parameters:

• r (float) – radius of circle.

• n (int) – number of points to fill the circle.

• alpha (float, optional) – parameter determining how smooth the boundary is. The default is 3.0.

• c (np.ndarray, shape = (2,), optional) – center of the circle. The default is np.array([0.0,0.0]).

• xlims (tuple, optional) – boundary in x-direction, points outside of this boundary will not be returned. The default is None.

• ylims (tuple, optional) – boundary in y-direction, points outside of this boundary will not be returned. The default is None.

Returns:

• pts (np.ndarray, shape = (n,2)) – array containing points which fill the circle.

• radius (np.ndarray, shape = (n,), optional) – array containing radius of each point from center c.

numbacs.utils.arclength(pts)

Compute total arclength of curve defined by pts.

Parameters:

pts (np.ndarray, shape=(npts,)) – points representing curve for which arclength is to be computed.

Returns:

arclength_ – arclength of curve defined by points.

Return type:

float

numbacs.utils.arclength_along_arc(pts)

Compute cummulative arclength at each point defining a curve.

Parameters:

pts (np.ndarray, shape=(npts,)) – points representing curve for which arclength is to be computed.

Returns:

arclength_ – array containing cummulative arclength of curve defined by pts.

Return type:

np.ndarray, shape = (npts,)

numbacs.utils.interp_curve(curve, n, s=0, k=3, per=0)

Return n interpolated values of curve.

Parameters:

• curve (np.ndarray, shape = (npts,2)) – array containing x,y-coordinates of curve being interpolated.

• n (int) – number of equally spaced interpolated points to return.

• s (float, optional) – smoothing parameter for spline, 0 will fit all data points exactly. The default is 0.

• k (int, optional) – degree of spline, using even numbers is not recommended, must be 1 <= k <= 5. The default is 3.

• per (int, optional) – if nonzero, data points are considered periodic. The default is 0.

Returns:

curvei – array containing interpolated values of curve.

Return type:

np.ndarray, shape = (n,2)

numbacs.utils.wn_pt_in_poly(polygon, point)

Winding number algorithm to determine if point is inside polygon. Based off of java implementation - https://observablehq.com/@jrus/winding-number - by Jacob Rus.

Parameters:

• polygon (np.ndarray, shape = (n,2)) – array containing vertices of polygon, first and last points should match.

• point (np.ndarray, shape = (2,)) – array containing the coordinates of point to be checked.

Returns:

wn – winding number, returns 1 if point is inside polygon and 0 if not.

Return type:

int

numbacs.utils.pts_in_poly(polygon, pts)

Checks if any point from pts is inside polygon. If a point is, the index of the first point found inside polygon is returned. Else, -1 is returned.

Parameters:

• polygon (np.ndarray, shape = (n,2)) – array containing vertices of polygon, first and last points should match.

• pts (np.ndarray, shape = (npts,2)) – array containing the coordinates of the points to be checked.

Returns:

if point from pts is found inside polygon, its index is returned, if not, -1 is returned.

Return type:

int

numbacs.utils.pts_in_poly_mask(polygon, pts)

Checks which points from pts are inside polygon. Returns a boolean mask corresponding to points inside polygon.

Parameters:

• polygon (np.ndarray, shape = (n,2)) – array containing vertices of polygon, first and last points should match.

• pts (np.ndarray, shape = (npts,2)) – array containing the coordinates of the points to be checked.

Returns:

mask – bool mask with indices matching those of pts, True if in polygon, False if not.

Return type:

np.ndarray, shape = (npts,)

numbacs.utils.cart_prod(vecs)

Computes the Cartesian product using vectors from vecs, works for any number of vectors.

Parameters:

vecs (tuple) – tuple containing vectors representing the sets which will be used to compute Cartestian product, all vectors must be 1D np.ndarrays of the same type.

Returns:

prod – array containing the Cartesian product.

Return type:

np.ndarray, shape = (npts,nvecs)

numbacs.utils.icosphere(subdivisions, r=1.0, dtype=float32, normalize_once=False)

Generate an icosphere using subdivisions=subdivisions, with radius r. If normalize_once is True, normalizing to the surface of the sphere will only happen at the very end, if not, normalization happens at every level of subdivision. The former is faster, the latter will produce more evenly spaced points.

Parameters:

• subdivisions (int) – number of subdivisions.

• r (float) – radius of sphere that the mesh will be defined on.

• dtype (numba.types or np.type, optional) – dtype used for the coordinates of the mesh, should be float32 or float64. The default is float32.

• normalize_once (bool, optional) – flag determining how normalization is handled. If normalize_once is True, normalizing to the surface of the sphere will only happen at the very end, if not, normalization happens at every level of subdivision. The former is faster, the latter will produce more evenly spaced points. The default is False.

Returns:

• verts (np.ndarray, shape=(10 * 4**subdivisions + 2, 3)) – array containing vertices of mesh.

• faces (np.ndarray, shape=(20 * 4**subdivisions, 3)) – array containing faces of mesh.

numbacs.utils.find_neighbors(faces, num_verts)

Finds all neighbors for each vertex.

numbacs.utils.convert_vel_to_3D(u, v, lon, lat, deg2rad=False, pole='both')

Convert velocity from lon-lat directions to xyz directions.

Parameters:

• u (np.ndarray, shape=(nt, nx, ny)) – velocity in the local east direction.

• v (np.ndarray, shape=(nt, nx, ny)) – velocity in the local north direction.

• lon (np.ndarray, shape=(nx,)) – array containing longitude values.

• lat (np.ndarray, shape=(ny,)) – array containing latitude values.

• deg2rad (bool, optional) – flag to determine if lon-lat need to be converted to radians. The default is False.

• pole (str, optional) – str to determine if any poles are included in the velocity fields. Options are “both”, “north”, or “south”. If pole is anything else, treated as no poles. The default is “both”.

Returns:

• vx (np.ndarray, shape=(nt, nx, ny)) – velocity in the x direction.

• vy (np.ndarray, shape=(nt, nx, ny)) – velocity in the y direction.

• vz (np.ndarray, shape=(nt, nx, ny)) – velocity in the z direction.

numbacs.utils.displacements_proj_ico(points, e1, e2, neighbors, mask=None)

Compute displacement array and project onto local coordinates.

Parameters:

• points (np.ndarray, shape=(nx, ny, 3)) – collection of (x, y, z) points.

• e1 (np.ndarray, shape = (nx, ny, 2)) – local “x” basis vector at each point.

• e2 (np.ndarray, shape = (nx, ny, 2)) – local “y” basis vector at each point.

• mask (None or np.ndarray, shape = (nx, ny), optional) – for masked data, pass in a boolean mask corresponding to nan values (True indicates a nan value). To avoid erroneous computations at mask boundaries, mask passed in should be dilated using the binary_mask_dilation_mesh function from the utils module. The default is None.

Returns:

X – array corresponding to displacements of n neighbors for each point.

Return type:

np.ndarray, shap=(nx, ny, 2, n)

numbacs.utils.lonlat2xyz(Lon, Lat, r, deg2rad=False, return_array=False)

Convert lon, lat positions to x, y, z.

Parameters:

• Lon (np.ndarray, shape=(nx, ny)) – meshgrid of longitude.

• Lat (np.ndarray, shape=(nx, ny)) – meshgrid of latitude.

• r (float) – radius.

• deg2rad (bool, optional) – flag to convert from degree to radians. Lon, Lat must either already be in radians, or this flag must be set to True. The default is False.

• return_array (bool, optional) – flag to return stacked array instead of tuple. The default is False.

Returns:

either tuple or stacked array containing meshgrid of X, Y, Z position.

Return type:

tuple or np.ndarray

numbacs.utils.local_basis_S2(Lon, Lat, deg2rad=False)

Create a local basis on the surface of the sphere (S2) in x, y, z coords.

Parameters:

• Lon (np.ndarray, shape=(nx, ny)) – meshgrid of longitude.

• Lat (np.ndarray, shape=(nx, ny)) – meshgrid of latitude.

• deg2rad (bool, optional) – flag to convert from degree to radians. Lon, Lat must either already be in radians, or this flag must be set to True. The default is False.

Returns:

• e1 (np.ndarray, shape=(nx, ny, 2)) – local basis vector in the “east” direction.

• e2 (np.ndarray, shape=(nx, ny, 2)) – local basis vector in the “north” direction.

numbacs.utils.xyz2lonlat(points, r, return_array=False)

Compute lon-lat coords from points, which are xyz coords.

Parameters:

• points (np.ndarray, shape = (npts, 3)) – array containing points in xyz coords.

• r (float) – radius of sphere.

• return_array (bool, optional) – flag to determine if tuple is returned (False) or array is returned (True). The default is False.

Returns:

tuple or array containing lon-lat coords of points.

Return type:

tuple or np.ndarray

numbacs.utils.xyz2lonlat_jit(points, r)

Compute lon-lat coords from points, which are xyz coords. JIT-compiled version.

Parameters:

• points (np.ndarray, shape = (npts, 3)) – array containing points in xyz coords.

• r (float) – radius of sphere.

Returns:

tuple or array containing lon-lat coords of points.

Return type:

np.ndarray, shape=(npts, 2)

numbacs.utils.local_basis_icosphere(lons, lats, deg2rad=False)

Create a local basis on the surface of the icosphere x, y, z coords.

Parameters:

• lons (np.ndarray, shape=(npts,)) – collection of longitude points defining the mesh.

• lats (np.ndarray, shape=(npts,)) – collection of latitude points defining the mesh.

• deg2rad (bool, optional) – flag to convert from degree to radians. lons, lats, must either already be in radians, or this flag must be set to True. The default is False.

Returns:

• e1 (np.ndarray, shape=(npts, 2)) – local basis vector in the “east” direction.

• e2 (np.ndarray, shape=(npts, 2)) – local basis vector in the “north” direction.

numbacs.utils.fill_nans_and_get_mask(arrs, fill_value=0.0)

For a collection of arrs with the same shape and same indices of nan values, obtain a boolean mask corresponding to the nan values and set the values of each arr to ‘fill_value’ wherever that mask is true. It is expected the same mask is to be applied for every slice of the leading dimension. Designed for data where the leading dimension is time, all other dimensions are spatial dimensions, and a spatial mask is being applied.

Parameters:

• arrs (tuple) – tuple of np.ndarrays, each should have the same size.

• fill_value (float, optional) – value to fill . The default is 0.0.

Returns:

tuple containing filled arrays and mask. Arrays will be shape=(nt, nx, ny), mask shape=(nx, ny).

Return type:

tuple

numbacs.utils.interpolate_mask_grid(mask, xp, yp, xq, yq)

Interpolate mask defined over (xp, yp), to a new mask, defined over (xq, yq). Points falling outside of initial grid will be masked.

Parameters:

• mask (np.ndarray, shape=(nxp, nyq)) – array of bools defining mask.

• xp (np.ndarray, shape=(nxp,)) – array containing x values at which mask was defined.

• yp (np.ndarray, shape=(nyp,)) – array containing y values at which mask was defined.

• xq (np.ndarray, shape=(nxq,)) – array containing x values at which new mask will defined.

• yq (np.ndarray, shape=(nyq,)) – array containing y values at which new mask will defined.

Returns:

new_mask – array of bools defining new mask.

Return type:

np.ndarray, shape=(nxq, nyq)

numbacs.utils.binary_mask_dilation(mask, corners=False)

Performs a binary dilation on a 2D structured grid boolean mask.

Parameters:

• mask (np.ndarray, shape=(nx, ny)) – boolean mask.

• corners (bool, optional) – if False (default), uses 4 cardinal neighbors. If True, 4 cardinal neighbors plus 4 corner neighbors.

Returns:

dilated_masl – the dilated mask.

Return type:

np.ndarray, shape=(nx, ny)

numbacs.utils.interpolate_mask_mesh(mask, xp, yp, mesh, convert=True, r=6371.0, wrap_x=True)

Interpolate mask defined over (xp, yp), to a new mask, defined over mesh. Points falling outside of initial grid will be masked.

Parameters:

• mask (np.ndarray, shape=(nxp, nyq)) – array of bools defining mask.

• xp (np.ndarray, shape=(nxp,)) – array containing x values at which mask was defined.

• yp (np.ndarray, shape=(nyp,)) – array containing y values at which mask was defined.

• mesh (np.ndarray, shape=(npts, 2) or (npts, 3)) – array containing (x, y) points defining the mesh.

• convert (bool, optional) – boolean determining if the points need to be converted from xyz to lon lat. The default is True.

• r (float, optional) – radius of sphere if mesh is defined on sphere. The default is 6371.0.

• wrap_x (bool, optional) – flag that determines if data is periodic in x, for data defined on the sphere, this should be set to True. The default is True.

Returns:

new_mask – array of bools defining new mask.

Return type:

np.ndarray, shape=(npts,)

numbacs.utils.binary_mask_dilation_mesh(mask, neighbors, first_points=12, less_neighbors=1)

Performs a binary dilation on a boolean mask over a mesh. The neighbors array contains the connected neighbors for each index of mask. If first_points > 0, the first points correspdonding to that value will only check n - less_neighbors since this function is designed for an icosphere mesh.

Parameters:

• mask (np.ndarray, shape=(npts,)) – boolean mask.

• neighbors (np.ndarray, shape=(npts, n)) – array containing neighbors for each vertex.

• first_points (int, optional) – determines how many points will be checked using n - less_neighbors neighbors. For the icosphere, the first 12 points will have 5 neighbors while all the rest will have 6. If every point in your mesh has the same number of neighbors, set this to 0. Must be nonnegative. The default is 12.

• less_neighbors (int, optional) – how many less neighbors will be checked for the first first_points points. Will have no affect if first_points=0. The default is 1.

Returns:

the dilated mask.

Return type:

np.ndarray, shape=(npts,)

numbacs.utils.icosphere_and_displacements(subdivisions, r=6371.0, normalize_once=False, mask_data=None)

Generate mesh for icosphere, find neighbors of each vertex, and compute displacements of each mesh point and its neighbors, projected onto local basis on the sphere.

Parameters:

• subdivisions (int) – number of subdivisions. For ftle calculations, 7 or 8 is sufficient. Any lower will produce under resolved ftle fields, any higher will result in long run times.

• r (float, optional) – radius of the sphere, will default to the radius of the earth (in km). The default is 6371.0.

• normalize_once (bool, optional) – flag determining how normalization is handled. If normalize_once is True, normalizing to the surface of the sphere will only happen at the very end, if not, normalization happens at every level of subdivision. The former is faster, the latter will produce more evenly spaced points. The default is False.

• mask_data (None or tuple, optional) – for masked data, pass in a tuple containing, pass in a boolean mask corresponding to nan values (True indicates a nan value) and the lon, lat, grid values which that mask was defined onn If mask_data is not None, a mesh_mask and dilated version will be returned. Pass these into flowmap_ND() and the ftle_icosphere() function respectively. The default is None.

Returns:

• verts (np.ndarray, shape=(10 * 4**subdivisions + 2, 3)) – array containing vertices of mesh.

• neighbors (np.ndarray, shape=(10 * 4**subdivisions + 2, 6)) – array containing indices of neighbors for each mesh point.

• X (np.ndarray, shape=(10 * 4**subdivisions + 2, 2, 6)) – array containing displacements for the neighbors of each mesh point.

• mesh_mask (np.ndarray, shape=(len(verts),), optional) – if mask is not None, a mask interpolated onto the mesh will be returned that can be passed into the flowmap_ND() function.

• dilated_mask (np.ndarray, shape=(len(verts),), optional) – if mask is not None, a dilated version of mesh_mask will be returned, which can be passed into ftle_icosphere() to avoid erroneous computations at mask boundaries.