numbacs.extraction

Extraction package for numbacs.

Submodules

Package Contents

numbacs.extraction.ftle_ridge_pts(f, eigvec_max, x, y, sdd_thresh=0.0, percentile=0)[source]

Compute FTLE ridge points by finding points (with subpixel accuracy) at which: ftle > 0 (or percentile of ftle), directional derivaitve of ftle (in eigvec_max direction) is 0, second directional derivative of ftle (in eigvec_max direction) is greater than sdd_thresh (in magnitude).

Parameters:

  • f (np.ndarray, shape = (nx,ny)) – ftle array.

  • eigvec_max (np.ndarray, shape = (nx,ny,2)) – maximum eigenvector of Cauchy Green tensor.

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

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

  • sdd_thresh (float, optional) – threshold for second directional derivative, should be at least 0. The default is 0.

  • percentile (int, optional) – percentile of ftle used for min allowed value. The default is 0.

Returns:

r_pts – ridge points.

Return type:

np.ndarray, shape = (ridge_bool.sum(),2)

numbacs.extraction.ftle_ridges(f, eigvec_max, x, y, sdd_thresh=0.0, percentile=0, min_ridge_pts=3)[source]

From ridge points from _ftle_ridges, extract connected ridges where a connected ridge is defined by a collection of points having continuous neighbors that are ridge points.

Parameters:

  • f (np.ndarray, shape = (nx,ny)) – ftle array.

  • eigvec_max (np.ndarray, shape = (nx,ny,2)) – maximum eigenvector of Cauchy Green tensor.

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

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

  • sdd_thresh (float, optional) – threshold for second directional derivative, should be at least 0. The default is 0.

  • percentile (int, optional) – percentile of ftle used for min allowed value. The default is 0.

  • min_ridge_pts (int) – minimum points allowed in ridge. The default is 3.

Returns:

list containing each connected ridge.

Return type:

list

numbacs.extraction.ftle_ordered_ridges(f, eigvec_max, x, y, dist_tol, ep_tan_ang=pi / 4, min_ridge_pts=5, sdd_thresh=0.0, percentile=0, c=1.0)[source]

Computes ftle ridge points and links points into ridges. After this is done, ridges that should be connected are searched for and connected if they meet certain critera. Criteria: if two ridges have endpoints that are within dist_tol and the angle between the tangent of the ridge at the endpoints and vector connecting the endpoints is less than ep_tan_ang, connect ridges.

Parameters:

  • f (np.ndarray, shape = (nx,ny)) – ftle array.

  • eigvec_max (np.ndarray, shape = (nx,ny,2)) – maximum eigenvector of Cauchy Green tensor.

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

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

  • dist_tol (float) – tolerance used to consider new endpoint for connection.

  • ep_tan_ang (float) – angle used to confirm endpoints are in line. The default is pi/4.

  • min_ridge_pts (int, optional) – minimum points allowed in ridge after endpoints are connected. The default is 5.

  • sdd_thresh (float, optional) – threshold for second directional derivative, should be at least 0.0. The default is 0.

  • percentile (int, optional) – percentile of ftle used for min allowed value. The default is 0.

  • c (float, optional) – scaling for angle portion of metric used in linking algorithm. The default is 1.0.

Returns:

ridges – list containing connected, ordered ridges.

Return type:

list

numbacs.extraction.hyperbolic_lcs(eigval_max, eigvecs, x, y, h, steps, lf, lmin, r, nmax, dist_tol, nlines, lambda_avg_min=0, percentile=0, ep_dist_tol=0.0, arclen_flag=False)[source]

Wrapper for _compute_lcs which also performs comparison of close enough LCS and returns most attracting/repelling LCS in a list.

Parameters:

  • eigval_max (np.ndarray, shape = (nx,ny)) – array containing maximum eigenvalues.

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

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

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

  • h (float) – step size used in Runge-Kutta solver.

  • steps (int) – maximum number of steps for Runge-Kutta solver.

  • lf (float) – maximum failure distance of LCS criteria allowed.

  • lmin (float) – minumum allowed length for LCS.

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

  • nmax (int) – number of maxima, i.e. initial conditions for tensorlines.

  • dist_tol (float) – distance tolerance used when comparing candidate LCS. If dist_tol = 0.0, no comparison will be made and all candidate LCS will be returned.

  • nlines (int) – number of lines in dimension with largest length used when comparing candidate LCS, number of lines in other dimension will be scaled by the ratio of the dimensions lengths. Only used if dist_tol > 0.

  • lambda_avg_min (int) – minimum allowed value for lambda_avg for curve to be considered for lcs. The default is 0.

  • percentile (int, optional) – percentile of eigval_max used for min allowed value. The default is 0.

  • ep_dist_tol (float, optional) – value used to compare starting/ending points of curves, if endpoints are within this value, all curves with smaller lambda_avg values are discarded. If ep_dist_tol <= 0.0, this step is skipped and endpoints are not compared. The default is 0.0.

  • arclen_flag (bool, optional) – flag to determine if the average attraction/repulsion rate along curve is used or if the total attraction/repulsion rate for a curve is used for comparison. The default is False.

Returns:

lcs – collection of most attracting/repelling LCS.

Return type:

list

numbacs.extraction.hyperbolic_oecs(eigval_max, eigvecs, x, y, r, h, steps, maxlen, minval, n=-1)[source]

Wrapper for _hyperbolic_oecs that returns list of oecs saddles.

Parameters:

  • eigval_max (np.ndarray, shape = (nx,ny)) – array containing values of max eigenvalue of S.

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

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

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

  • r (float) – radius used to find local maxima.

  • h (float) – step size used in Runge-Kutta solver.

  • steps (int) – maximum number of steps for Runge-Kutta solver.

  • maxlen (float) – maximum allowed length for oecs curve.

  • minval (float) – minimum value allowed for eigval_max.

  • n (int, optional) – number of local maxima to look for, if n = -1, all are used. The default is -1.

Returns:

oecs_saddles – list containing oecs saddles defined by oecs forward and oecs backward curves.

Return type:

list

numbacs.extraction.rotcohvrt(lavd, x, y, r, convexity_method='convex_hull', convexity_deficiency=0.005, min_val=-1.0, nlevs=20, start_level=0.0, end_level=0.0, min_len=0.0)[source]

Compute rotationally coherent vortices which are (approximately) convex closed contours of the lavd (or ivd) field.

Parameters:

  • lavd (np.ndarray, shape = (nx,ny)) – array containing lavd values.

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

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

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

  • convexity_method (str, optional) – method used to determine if closed curve is convex, options are ‘convex_hull’ which calculates the relative difference in area of the curve and its convex hull, ‘angle’ which checks if angle between succesive edges exceeds convexity_deficiency in the negative direction. The default is ‘convex_hull’.

  • convexity_deficiency (float, optional) – value used to allow convexity deficiency up to this value, if ‘convex_hull’ method is used this is the allowable relative difference in area, if ‘angle’ method is used this is the allowable angle. The default is 5e-3.

  • min_val (float, optional) – minimum value allowed for maxima of the lavd field, if equals -1.0, the 80th percentile of the lavd is used. The default is -1.0.

  • nlevs (int, optional) – number of levels of contours to use when searching for convex curves. The default is 20.

  • start_level (float, optional) – starting level of contours for search, if equals 0.0 then the 70th percentile of the lavd is used. The default is 0.0.

  • end_level (float, optional) – value for last contour level to be checked, if equals 0.0 then the maximum of the lavd is used. The default is 0.0.

Returns:

rcv – list containing rotationally coherent vortices and corresponding vortex centers.

Return type:

list