numbacs.utils ============= .. py:module:: numbacs.utils Module Contents --------------- .. py:function:: 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). :param index: raveled index. :type index: int :param shape: shape of array used for unraveling index. :type shape: np.ndarray, shape = (ndims,) :returns: array containing the unraveled index. :rtype: np.ndarray .. py:function:: 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. :param inds: array containing indices to be raveled. :type inds: np.ndarray, shape = (ndims,) :param shape: shape of array used for raveling index. :type shape: np.ndarray, shape = (ndims,) :returns: **r_ind** -- raveled index. :rtype: int .. py:function:: 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. :param f: array on which finite differencing is performed. :type f: np.ndarray, shape = (nx,ny) :param i: index for axis=0 at which finite differencing is performed. :type i: int :param j: index for axis=1 at which finite differencing is performed. :type j: int :param h: spacing in axis direction. :type h: float :param axis: axis over which finite differencing is performed. :type axis: int :param direction: finite differencing direction, optional values are 'b' for backward, 'c' for centered, and 'f' for forward. The default is 'c'. :type direction: str, optional :returns: **df** -- finite difference value. :rtype: float .. py:function:: 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. :param f: flattened array of which finite differencing is performed. :type f: np.ndarray, shape = (nx_1*nx_2*...*nx_ndims,) :param ind: raveled index at which finite differencing is performed. :type ind: int :param h: spacing in axis direction. :type h: float :param axis: axis over which finite differencing is performed. :type axis: int :param shape: shape of original array before raveled. :type shape: np.ndarray, shape = (ndims,) :param direction: finite differencing direction, optional values are -1 for backward, 0 for centered, and 1 for forward. The default is 0. :type direction: str, optional :returns: **df** -- finite difference value. :rtype: float .. py:function:: 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. .. py:function:: curl_vel(u, v, dx, dy) Compute curl of vector field defined by u and v. :param u: array containing x component of vector field. :type u: np.ndarray, shape = (nx,ny) :param v: array containing y component of vector field. :type v: np.ndarray, shape = (nx,ny) :param dx: spacing in grid in x-direction. :type dx: float :param dy: spacing in grid in y-direction. :type dy: float :returns: **curl** -- array containing values of curl of vector field defined by u and v. :rtype: np.ndarray, shape = (nx,ny) .. py:function:: curl_vel_tspan(u, v, dx, dy) Compute curl of vector field defined by u and v over some timespan. :param u: array containing x component of vector field. :type u: np.ndarray, shape = (nt,nx,ny) :param v: array containing y component of vector field. :type v: np.ndarray, shape = (nt,nx,ny) :param dx: spacing in grid in x-direction. :type dx: float :param dy: spacing in grid in y-direction. :type dy: float :returns: **curl** -- array containing values of curl of vector field defined by u and v. :rtype: np.ndarray, shape = (nt,nx,ny) .. py:function:: curl_func(fnc, x, y, h=0.001) Compute curl over x,y of vector field defined by fnc. :param fnc: callable containing returing x and y components of vector field. :type fnc: jit-callable :param x: array containing x-values. :type x: np.ndarray, shape = (nx,) :param y: array containing y-values. :type y: np.ndarray, shape = (ny,) :param h: spacing used in finite differencing. The default is 1e-3. :type h: float, optional :returns: **curlf** -- array containing values of curl of f. :rtype: np.ndarray, shape = (nx,ny) .. py:function:: curl_func_tspan(fnc, t, x, y, h=0.001) Compute curl over x,y of vector field defined by func over times t. :param fnc: callable containing returing x and y components of vector field. :type fnc: jit-callable :param x: array containing x-values. :type x: np.ndarray, shape = (nx,) :param y: array containing y-values. :type y: np.ndarray, shape = (ny,) :param h: spacing used in finite differencing. The default is 1e-3. :type h: float, optional :returns: **curlf** -- array containing values of curl of f. :rtype: np.ndarray, shape = (nx,ny) .. py:function:: 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. :param f: values of f at regularly spaced points. :type f: np.ndarray, shape = (n+1,) :param h: value of spacing between points at which f was evaluated. :type h: float :returns: **val** -- value of integral. :rtype: float .. py:function:: 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. :param f: values of f at irregularly spaced points. :type f: np.ndarray, shape = (n+1,) :param h: values of spacing between points at which f was evaluated. :type h: np.ndarray, shape = (n,) :returns: **val** -- value of integral. :rtype: float .. py:function:: dist_2d(p1, p2) Compute 2D Euclidean distance between p1 and p2. :param p1: point 1. :type p1: np,ndarry, shape = (2,) :param p2: point 2. :type p2: np,ndarry, shape = (2,) :returns: distance between p1 and p2. :rtype: float .. py:function:: dist_tol(point, arr, tol) Check if pt is within tolerance of any point in arr. :param point: point. :type point: np.ndarray, shape = (2,) :param arr: array containing points. :type arr: np.ndarray, shape = (n,2) :param tol: tolerance used for checking distance. :type tol: float :returns: **near** -- truth value determining if point is within tol of any point in arr. :rtype: boolean .. py:function:: shoelace(polygon) Compute area of simple polygon using shoelace algorithm. :param polygon: array containing vertices of polygon, first and last vertex should be the same. :type polygon: np.ndarray, shape = (n,2) :returns: **area** -- area of polygon. :rtype: float .. py:function:: 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()). :param arr: array in which local maxima are to be found. :type arr: np.ndarray, shape = (nx,ny) :param r: radius in which points will be discared after a maximum is found at the center. :type r: float :param dx: gird spacing in x-direction. :type dx: float :param dy: grid spacing in y-direction. :type dy: float :param n: number of maxima to return, -1 returns all. The default is -1. :type n: int, optional :param min_val: miniumum value allowed for local maxima. The default is 0.0. :type min_val: float, optional :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. .. py:function:: gen_circ(r, c, n, xlims=None, ylims=None) Generate n points on a circle with radius r and center c. :param r: radius of circle. :type r: float :param c: center of circle. :type c: np.ndarray, shape = (2,) :param n: number of points on circle. :type n: int :param xlims: boundary in x-direction, points outside of this boundary will not be returned. The default is None. :type xlims: tuple, optional :param ylims: boundary in y-direction, points outside of this boundary will not be returned. The default is None. :type ylims: tuple, optional :returns: **pts** -- points on the circle. :rtype: np.ndarray, shape = (n,2) .. py:function:: 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. :param r: radius of circle. :type r: float :param n: number of points to fill the circle. :type n: int :param alpha: parameter determining how smooth the boundary is. The default is 3.0. :type alpha: float, optional :param c: center of the circle. The default is np.array([0.0,0.0]). :type c: np.ndarray, shape = (2,), optional :param xlims: boundary in x-direction, points outside of this boundary will not be returned. The default is None. :type xlims: tuple, optional :param ylims: boundary in y-direction, points outside of this boundary will not be returned. The default is None. :type ylims: tuple, optional :returns: **pts** -- array containing points which fill the circle. :rtype: np.ndarray, shape = (n,2) .. py:function:: 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. :param r: radius of circle. :type r: float :param n: number of points to fill the circle. :type n: int :param alpha: parameter determining how smooth the boundary is. The default is 3.0. :type alpha: float, optional :param c: center of the circle. The default is np.array([0.0,0.0]). :type c: np.ndarray, shape = (2,), optional :param xlims: boundary in x-direction, points outside of this boundary will not be returned. The default is None. :type xlims: tuple, optional :param ylims: boundary in y-direction, points outside of this boundary will not be returned. The default is None. :type ylims: tuple, optional :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. .. py:function:: arclength(pts) Compute total arclength of curve defined by pts. :param pts: points representing curve for which arclength is to be computed. :type pts: np.ndarray, shape=(npts,) :returns: **arclength_** -- arclength of curve defined by points. :rtype: float .. py:function:: arclength_along_arc(pts) Compute cummulative arclength at each point defining a curve. :param pts: points representing curve for which arclength is to be computed. :type pts: np.ndarray, shape=(npts,) :returns: **arclength_** -- array containing cummulative arclength of curve defined by pts. :rtype: np.ndarray, shape = (npts,) .. py:function:: interp_curve(curve, n, s=0, k=3, per=0) Return n interpolated values of curve. :param curve: array containing x,y-coordinates of curve being interpolated. :type curve: np.ndarray, shape = (npts,2) :param n: number of equally spaced interpolated points to return. :type n: int :param s: smoothing parameter for spline, 0 will fit all data points exactly. The default is 0. :type s: float, optional :param k: degree of spline, using even numbers is not recommended, must be 1 <= k <= 5. The default is 3. :type k: int, optional :param per: if nonzero, data points are considered periodic. The default is 0. :type per: int, optional :returns: **curvei** -- array containing interpolated values of curve. :rtype: np.ndarray, shape = (n,2) .. py:function:: 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. :param polygon: array containing vertices of polygon, first and last points should match. :type polygon: np.ndarray, shape = (n,2) :param point: array containing the coordinates of point to be checked. :type point: np.ndarray, shape = (2,) :returns: **wn** -- winding number, returns 1 if point is inside polygon and 0 if not. :rtype: int .. py:function:: 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. :param polygon: array containing vertices of polygon, first and last points should match. :type polygon: np.ndarray, shape = (n,2) :param pts: array containing the coordinates of the points to be checked. :type pts: np.ndarray, shape = (npts,2) :returns: if point from pts is found inside polygon, its index is returned, if not, -1 is returned. :rtype: int .. py:function:: pts_in_poly_mask(polygon, pts) Checks which points from pts are inside polygon. Returns a boolean mask corresponding to points inside polygon. :param polygon: array containing vertices of polygon, first and last points should match. :type polygon: np.ndarray, shape = (n,2) :param pts: array containing the coordinates of the points to be checked. :type pts: np.ndarray, shape = (npts,2) :returns: **mask** -- bool mask with indices matching those of pts, True if in polygon, False if not. :rtype: np.ndarray, shape = (npts,) .. py:function:: cart_prod(vecs) Computes the Cartesian product using vectors from vecs, works for any number of vectors. :param vecs: 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. :type vecs: tuple :returns: **prod** -- array containing the Cartesian product. :rtype: np.ndarray, shape = (npts,nvecs)