numbacs.diagnostics

Module Contents

numbacs.diagnostics.ftle_grid_2D(flowmap, T, dx, dy, mask=None)

Compute 2D FTLE field from flowmap which is solution of ode over an initial grid defined by x and y for integration time T.

Parameters:

• flowmap (np.ndarray, shape = (nx, ny, 2)) – array containing final positions of trajectories of initial grid from t0 to t0+T.

• T (float) – integration time.

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

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

• 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 function from the utils module. The default is None.

Returns:

ftle – array containing ftle values.

Return type:

np.ndarray, shape = (nx,ny)

numbacs.diagnostics.C_tensor_2D(flowmap_aux, dx, dy, h=1e-05, mask=None)

Compute eigenvalues and eigenvectors of Cauchy Green tensor in 2D from flowmap_aux which is solution of ode over an auxilary grid defined by x,y +-h for integration time T.

Parameters:

• flowmap_aux (np.ndarray, shape = (nx, ny, n_aux, 2)) – array containing final positions of initial grid with aux grid spacing h from t0 to t0+T.

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

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

• h (float, optional) – aux grid spacing. The default is 1e-5.

• 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). The default is None.

Returns:

C – array containing C11, C12, C22 components of Cauchy Green tensor.

Return type:

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

numbacs.diagnostics.C_eig_aux_2D(flowmap_aux, dx, dy, h=1e-05, eig_main=True, mask=None)

Compute eigenvalues and eigenvectors of Cauchy Green tensor in 2D from flowmap_aux which is solution of ode over an auxilary grid defined by x,y +-h for integration time T.

Parameters:

• flowmap_aux (np.ndarray, shape = (nx,ny,n_aux,2)) – array containing final positions of initial grid with aux grid spacing h from t0 to t0+T.

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

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

• h (float, optional) – aux grid spacing. The default is 1e-5.

• eig_main (boolean, optional) – flag to determine if eigevalues are computed from main grid. The default is True.

• 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 (if eig_main=True), mask passed in should be dilated using the binary_mask_dilation function from the utils module. The default is None.

Returns:

• eigvals (np.ndarray, shape = (nx,ny,2)) – array containing eigenvalues values.

• eigvecs (np.ndarray, shape = (nx,ny,2,2)) – array containing eigenvectors.

numbacs.diagnostics.C_eig_2D(flowmap, dx, dy, mask=None)

Compute eigenvalues and eigenvectors of Cauchy Green tensor in 2D from flowmap which is solution of ode over a grid defined by x,y for integration time T.

Parameters:

• flowmap (np.ndarray, shape = (nx, ny, 2)) – array containing final positions of initial grid from t0 to t0+T.

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

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

• 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 function from the utils module. The default is None.

Returns:

• eigvals (np.ndarray, shape = (nx, ny, 2)) – array containing eigenvalues.

• eigvecs (np.ndarray, shape = (nx, ny, 2, 2)) – array containing eigenvectors.

numbacs.diagnostics.ftle_from_eig(eigval_max, T)

Compute FTLE field from eigval_max where eigval_max is eigenvalue of Cauchy-Green tensor computed using integration time T.

Parameters:

• eigval_max (np.ndarray, shape = (nx,ny)) – maximum eigenvalue of Cauchy-Green tensor computed using integration time T.

• T (float) – integration time.

Returns:

ftle – array containing ftle values.

Return type:

np.ndarray, shape = (nx,ny)

numbacs.diagnostics.lavd_grid_2D(flowmap_n, tspan, T, vort_interp, xrav, yrav, period_x=0.0, period_y=0.0, mask=None)

Compute LAVD from flowmap_n where flowmap_n contains trajectories computed over gridpoints defined by xrav,yrav for an integration time T and trajectories are returned at times given by tspan. vort_interp is an interpolant function of vorticity over (at least) that time window.

Parameters:

• flowmap_n (np.ndarray, shape = (nx, ny, n, 2)) – array containing trajectories of initial grid from t0 to t0+T.

• tspan (np.ndarray, shape = (n,)) – array containing n times corresponding to axis=2 of flowmap_n.

• T (float) – integration time.

• vort_interp (jit-callable) – interpolant function of vorticity which must be (at least) defined over all values of flowmap_n and times from tspan.

• xrav (np.ndarray, shape = (nx*ny,))) – array containing raveled or flattened meshgrid X, can be obtained using X.ravel() or X.flatten().

• yrav (np.ndarray, shape = (nx*ny,))) – array containing raveled or flattened meshgrid Y, can be obtained using Y.ravel() or Y.flatten().

• period_x (float) – value for period in x-direction, if not periodic, set equal to 0.0. The default is 0.0.

• period_y (float) – value for period in y-direction, if not periodic, set equal to 0.0. The default is 0.0.

• 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). The default is None.

Returns:

lavd – array containing lavd values.

Return type:

np.ndarray, shape = (nx,ny)

numbacs.diagnostics.ftle_grid_ND(flowmap, IC, T, dX)

Compute ND FTLE field from flowmap which is solution of ode over an initial grid defined by IC for integration time T.

Parameters:

• flowmap (np.ndarray, shape = (nx_1*nx_2*...*nx_ndims,ndims)) – array containing final positions of initial grid from t0 to t0+T.

• IC (np.ndarray, shape = (nx_1,nx_2,...,nx_ndims,ndims)) – initial condition array.

• T (float) – integration time.

• dX (np.ndarray, shape = (ndims,)) – array containing spacing in each x_i direction for i = 1,…,ndims.

Returns:

ftle – array containing ftle values.

Return type:

np.ndarray, shape = (nx_1*nx_2*…*nx_ndims,)

numbacs.diagnostics.displacement_array_proj(points, e1, e2, full=True, 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.

• full (bool, optional) – flag to determine if full 8 (True) neighbors of grid point are used or just 4 (False). The default is True.

• 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 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.diagnostics.ftle_grid_S2(Lon, Lat, flowmap, T, r=6371.0, full=True, X=None, deg2rad=True, mask=None)

Computes a more accurate approximation of FTLE on the surface of the sphere (S2). Uses the least-squares approximation of the FTLE based on grid cell displacements in 3D space. For more info on the background theory, see Lekien and Ross, “The computation of finite-time Lyapunov exponents on unstructured meshes and for non-Euclidean manifolds”. doi: 10.1063/1.3278516.

Parameters:

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

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

• flowmap (np.ndarray, shape=(nx, ny, 2)) – final particle positions for whole grid in lon-lat coords.

• T (float) – integration time.

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

• full (bool, optional) – flag to determine if full 8 neighbors of grid point are used or just 4. The default is True.

• X (None or np.ndarray, shape=(nx, ny, 2, n)) – initial displacement array that contains the displacement of each grid points from its n neighbors (determined by full). This can be computed by first computing initial_points = numbacs.utils.lonlat2xy(Lon, Lat, r, deg2rad=True, return_array=True). Then, e1, e2 = numbacs.utils.local_basis_S2(Lon, Lat, deg2rad=True). Then passing the results to X = displacement_array_proj(initial_points, e1, e2, full=full, mask=mask, dilate_mask=dilate_mask). This is useful if you are computing ftle in a time series, by passing is this array you avoid this redundent computation for every iterate. If None, this will be computed internally everytime this function is called. The default is None.

• 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. Not relevant and will be ignored if X is not None. The default is True.

• 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 function from the utils module. The default is None.

Returns:

least-squares approximation of ftle on the sphere.

Return type:

np.ndarray, shape=(nx, ny)

numbacs.diagnostics.ftle_icosphere(flowmap, neighbors, X, T, mask=None)

Computes FTLE on the surface of the sphere (S2), where the sphere is defined by mesh_points which are vertices of an icosphere. Uses the least-squares approximation of the FTLE based on mesh cell displacements in 3D space. For more info on the background theory, see Lekien and Ross, “The computation of finite-time Lyapunov exponents on unstructured meshes and for non-Euclidean manifolds”. doi: 10.1063/1.3278516.

Parameters:

• flowmap (np.ndarray, shape=(npts, 3)) – final particle positions for whole mesh in xyz-coords.

• neighbors (np.ndarray, shape=(npts, 6)) – array containing neighbors of initial mesh points. Can be obtained from the following function - mesh_points, neighbors, X = numbacs.utils.icosphere_and_displacements(subdivisions, r=r, mask=mask).

• X (np.ndarray, shape=(npts, 2, 6)) – array containing intial projected displacements.Can be obtained from same function as neighbors - mesh_points, neighbors, X = numbacs.utils.icosphere_and_displacements(subdivisions, r=r, mask=mask).

• T (float) – integration time.

• mask (None or np.ndarray, shape = (npts,), 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:

least-squares approximation of ftle on the sphere.

Return type:

np.ndarray, shape=(npts,)

numbacs.diagnostics.ile_2D_func(vel, x, y, t0=None, h=0.001, mask=None)

Compute the iLE field from the flow defined by vel which is a jit-callable function, step size of h is used in finite differencing.

Parameters:

• vel (jit-callable) – function returing interpolated of function value of velocity in x,y directions.

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

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

• t0 (float or None, optional) – time value at which to evaluate if v1,v2 interpolants depend on time, if they do not depend on time, set to None. The default is None.

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

• 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). The default is None.

Returns:

ile – array containing ile values.

Return type:

np.ndarray, shape = (nx,ny)

numbacs.diagnostics.S_eig_2D_func(vel, x, y, t0=None, h=0.001, mask=None)

Compute eigenvalues and eigenvectors of Eulerian rate of strain tensor in 2D from vel which is a jit-callable function, step size of h is used for finite differencing.

Parameters:

• vel (jit-callable) – function returing interpolated of function value of velocity in x,y directions.

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

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

• t0 (float or None, optional) – time value at which to evaluate if v1,v2 interpolants depend on time, if they do not depend on time, set to None. The default is None.

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

• 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). The default is None.

Returns:

• eigvals (np.ndarray, shape = (nx, ny)) – array containg eigenvalues of S.

• eigvecs (np.ndarray, shape = (nx, ny)) – array containing eigenvectors of S.

numbacs.diagnostics.S_2D_func(vel, x, y, t0=None, h=0.001, mask=None)

Compute Eulerian rate of strain tensor in 2D from vel which is a jit-callable functions, step size of h is used for finite differencing.

Parameters:

• v1 (jit-callable) – function returing interpolated value of velocity in x-direction.

• v2 (jit-callable) – function returing interpolated value of velocity in y-direction.

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

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

• t0 (float or None, optional) – time value at which to evaluate if v1,v2 interpolants depend on time, if they do not depend on time, set to None. The default is None.

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

• 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). The default is None.

Returns:

S – S11,S12, and S22 components of S tensor.

Return type:

np.ndarray, shape = (nx,ny)

numbacs.diagnostics.ile_2D_data(u, v, dx, dy, mask=None)

Compute the iLE field from the flow defined by u,v over an intial grid defined by x,y.

Parameters:

• u (np.ndarray, shape = (nx,ny)) – array containing velocity values in x-direction.

• v (np.ndarray, shape = (nx,ny)) – array containing velocity values in y-direction.

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

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

• 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 function from the utils module. The default is None.

Returns:

ile – array containing ile values.

Return type:

np.ndarray, shape = (nx,ny)

numbacs.diagnostics.S_eig_2D_data(u, v, dx, dy, mask=None)

Compute eigenvalues and eigenvectors of Eulerian rate of strain tensor in 2D from u,v which describe the x,y velocity.

Parameters:

• u (np.ndarray, shape = (nx, ny)) – array containing velocity values in x-direction.

• v (np.ndarray, shape = (nx, ny)) – array containing velocity values in y-direction.

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

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

• 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 function from the utils module. The default is None.

Returns:

• eigvals (np.ndarray, shape = (nx, ny, 2)) – array containg eigenvalues of S.

• eigvecs (np.ndarray, shape = (nx, ny, 2, 2)) – array containing eigenvectors of S.

numbacs.diagnostics.ivd_grid_2D(vort, vort_avg)

Compute IVD at an instant from vort and vort_avg.

Parameters:

• vort (np.ndarray, shape = (nx, ny)) – array containg vorticity values.

• vort_avg (float) – value of average spatial vorticity at specific time.

Returns:

ivd – array containing values of ivd.

Return type:

np.ndarray, shape = (nx, ny)