Give two numeric 1-D arrays X and Y, of the same size,
        do a least-square fit: Y = a + b * X , for some numbers a and b

        :param X:   A numpy numeric 1-D array
        :param Y:   A numpy numeric 1-D array, with the same number of elements as X
        :return:    A pair of numbers (a, b) that provide the least-square fit for Y = a + b * X
        

        Give three numeric 1-D arrays V, W and Y, of the same size,
        do a least-square fit: Y = a * V + b * W, for some numbers a and b

        :param V:
        :param W:
        :param Y:
        :return:
        

        Given a set of 2-D points, whose x- and y- coordinates are stored, respectively, in the
        columns whose names are given by the arguments x and y, locate the x-coordinate at which
        the curve first reaches the given y-value threshold.
        That is, its intersection with the horizontal line y = y_threshold
        Linear interpolation is used.

        The dataframe is *assumed* sorted by the x variable, increasing monotonically; an Exception is
        raised if that's not the case.
        
        Note that if there are multiple intersections, only the leftmost (smallest x) is returned.

        In case no intersection is found, None is returned.

        :param df:          A Pandas dataframe with at least 2 columns
        :param x:           The name of the column with the x-values
        :param y:           The name of the column with the y-values
        :param y_threshold: A number with a y-value being sought in the xy curve
        :return:            The x-value at which the linearly-interpolated curve first reaches
                                the y-value y_threshold, or None if not found
        

        Determine the intersection point between 2 Pandas dataframe columns,
        using linear interpolation.
        If more than one is present, only the first (smallest value of x-coord) one will be returned;
        so, the specified time interval should be narrow enough to bracket the intersection of interest

        :param df:      A Pandas dataframe with at least 3 columns
        :param x:       The name of the dataframe column with the independent variable
        :param var1:    The name of the dataframe column with the data from the 1st curve
        :param var2:    The name of the dataframe column with the data from the 2nd curve
        :param explain: [OPTIONAL] If True, print out some details of the computation
        :return:        The pair (x-coordinate of intersection, common value)

        :return:        The pair (x-coordinate of intersection, common value)
        

        Find the intersection of two segments in 2D.
        Their respective endpoints share the same x-coordinates: (t_start, t_end)

        Note: for an alternate method, see line_intersect()

        :param t:   Pair with the joint x-coordinates of the 2 start points,
                        and the joint x-coordinates of the 2 end points
        :param y1:  Pair with the y_coordinates of the endpoints of the 1st segment
        :param y2:  Pair with the y_coordinates of the endpoints of the 2nd segment
                        Note: either segment - but not both - may be horizontal

        :return:    A pair with the (x,y) coord of the intersection;
                        if the segments don't meet their specs (which might result in the lack of an intersection),
                        an Exception is raised
        

        Returns the coordinates of the intersection
        between the line passing thru the points p1 and p2,
        and the line passing thru the points q1 and q2.

        Based on https://stackoverflow.com/a/42727584/5478830

        Note: for an alternate method, see segment_intersect()

        :param p1:  Pair of (x,y) coord of a point on the 1st line
        :param p2:  Pair of (x,y) coord of another point on the 1st line
        :param q1:  Pair of (x,y) coord of a point on the 2nd line
        :param q2:  Pair of (x,y) coord of another point on the 2nd line

        :return:    A pair with the (x,y) coord of the intersection, if it exists;
                        or None if it doesn't exist
        

        Completely flatten any lists/tuples of lists or tuples
        into a single list
        EXAMPLES:
            [[1,2,3], [4,5,6], [7], [8,9]] becomes [1, 2, 3, 4, 5, 6, 7, 8, 9]
            (1,2)                       becomes [1,2]
            [(1, 2), (3,4)]             becomes [1, 2, 3, 4]
            5                           becomes [5]
            "hello"                     becomes ["hello"]

        :param items:   A list or tuple possibly containing lists or tuples
        :return:        A flat list
        

        Use a Euclidean distance metric to compare 2 sets of results - typically from 2 runs
        of different accuracy.
        Each result value may be a number or a list or tuple, possibly containing lists or tuples,
        of numbers.
        However, after the structure is flattened,
        the 2 result data sets must have the same number of points

        :param res1:
        :param res2:
        :return:    The distance between the two sets of value, based on an L2 (Euclidean) metric
        

        Return the Euclidean distance between the two given same-sized Numpy arrays

        :param v1:
        :param v2:
        :param metric:      NOT YET USED: the default L2 norm is always used
        :param trim_edges:  (OPTIONAL) number of elements to ditch at each end,
                                prior to comparing the vectors (default: 0)
        :return:            The distance between the two vectors based on an L2 (Euclidean) metric
        

        Print out various assessments of how similar two same-sized Numpy arrays are.
        Typically, those arrays will be system state snapshots - but could be anything.

        :param state1:
        :param state2:
        :param verbose: If True, additional output is shown
        :return:        None
        

        Compute the gradient, from UNIT-SPACED x-values and y-values in the given 1-dimensional array,
        using the 5-point Central Difference, which produces an accuracy of order 4.

        At the boundary, or close to it, different 5-point stencils are used,
        still resulting in an accuracy of order 4.
        For the coefficients, see: https://web.media.mit.edu/~crtaylor/calculator.html

        Returns the same size as the input array.

        Note:
            * For multi-dimensional cases, use gradient_order4()
            * For a simpler, but less accurate (order 2) approach, use Numpy gradient(),
              which is also usable in case of uneven grids of x values

        :param arr:     One-dimensional Numpy array (or list, or tuple) of numbers,
                            with at least 5 elements
        :param dx:      Delta_x (assumed constant)
        :param dtype:   Data type to use for the elements of the returned array

        :return:        A Numpy array with the same size as the one passed in arr
        

        Compute the gradient, from the values in the given (possibly multidimensional) array,
        using the 5-point Central Difference, which produces an accuracy of order 4.

        All points need to be equally-spaced along each dimension.

        At the boundary, and at the points immediately adjacent to the boundary,
        the gradient is computed by the very simple 2-point forward or backward differences (accuracy order 1.)

        It returns a list of ndarrays (or a single ndarray if there is only 1 dimension).
        Each list element has the same shape as the original array,
        and corresponds to the derivatives of the passed array with respect to each dimension.

        For 1-dimensional cases, can also use gradient_order4_1d(), which produces accuracy order 4 at ALL points.

        (ADAPTED FROM https://gist.github.com/deeplycloudy/1b9fa46d5290314d9be02a5156b48741 ,
        which is based on 2nd order version from
        http://projects.scipy.org/scipy/numpy/browser/trunk/numpy/lib/function_base.py

        :param f:       An N-dimensional array giving samples of a scalar function
        :param varargs: 0, 1, or N scalars giving the sample distances in each direction

        :return:        A list of N numpy arrays,
                        each of the same shape as f giving the derivative of f with respect to each dimension
        

        Compute and return the gradient of a 1-D function f(x) at the given grid points,
        which may be uneven.  An arbitrary stencil ("sliding window") size may be used.

        For gradients (first derivatives), the accuracy will be dependent on the size of
        the stencil - though overly large stencils might lead to oscillations.

        Based on B. Fornberg, "Calculation of Weights in Finite Difference Formulas", 1998
        (https://epubs.siam.org/doi/abs/10.1137/S0036144596322507)

        :param x_values:    A Numpy array of x values (independent variable) that
                                may be unevenly-spaced
        :param f:           A Numpy array of the values of the function at the above grid point
        :param stencil:     An integer between 2 and the number of grid points.
        :return:            A Numpy array
        

        Compute and return the specified derivative order (by default the gradient)
        of a 1-D function f(x) at the  point x=z.
        The entire grid of values is used as a stencil.

        :param z:               x value (in grid or not) at which to compute the gradient of f
        :param window_x_arr:    Grid point locations
        :param window_f_arr:    Values of the function at the above grid points
        :param order:           Order of the derivative (by default 1st derivative, i.e. gradient)
        :return:                A floating-point value
        

        Based on B. Fornberg, "Calculation of Weights in Finite Difference Formulas", 1998
        (https://epubs.siam.org/doi/abs/10.1137/S0036144596322507)

        :param z:   x value (in grid or not) where approximations are to be accurate
        :param x:   Grid point locations, x0 thru xn : (n+1) of them
        :param m:   Highest derivative for which weights are sought.
                        EXAMPLE : m=1 to compute up to 1st derivative (gradient)

        :return:    (n+1) x (m+1) Numpy array:
                        c(i, j) stores the weights at grid locations x(i) for derivatives of order j,
                        with 0 <= i <= n , and 0 <= j < m, and n being one less than total number of grid points
        

        Add a row at the top and at the bottom, and also add a column to the left and to the right,
        repeating the edge values of the matrix
        EXAMPLE:  [[1, 2],
                   [3, 4]]
                 will turn to
                  [[1, 1, 2, 2],
                   [1, 1, 2, 2],
                   [3, 3, 4, 4],
                   [3, 3, 4, 4]]
                 Note how the original matrix is "embedded" in the center of the larger one

        :param m:   A Numpy matrix
        :return:    A Numpy matrix, with 2 extra rows (at top and bottom) and 2 extra columns (at left and right)