seisflows.tools.math
====================

.. py:module:: seisflows.tools.math

.. autoapi-nested-parse::

   Mathematical tools for Seisflows



Functions
---------

.. autoapisummary::

   seisflows.tools.math.angle
   seisflows.tools.math.dot
   seisflows.tools.math.hilbert
   seisflows.tools.math.poissons_ratio
   seisflows.tools.math.parabolic_backtrack
   seisflows.tools.math.gaussian
   seisflows.tools.math.polynomial_fit
   seisflows.tools.math.lsq2
   seisflows.tools.math.nabla
   seisflows.tools.math.nabla2
   seisflows.tools.math.grad
   seisflows.tools.math.tv


Module Contents
---------------

.. py:function:: angle(x, y)

   Determine the angle between two vectors using dot products

   :type x: np.array
   :param x: vector 1
   :type y: np.array
   :param y: vector 2
   :rtype: float
   :return: the angle in degrees between `x` and `y`


.. py:function:: dot(x, y)

   Calculate the dot product between two vectors

   :type x: np.array
   :param x: vector 1
   :type y: np.array
   :param y: vector 2
   :rtype: float
   :return: The dot product between `x` and `y`


.. py:function:: hilbert(w)

   Take the Hilbert transform of some function to get the analytic signal

   TODO Change the naming here, it seems confusing to rename a scipy function
   TODO and then overwrite its name with this function.

   :type w: np.array
   :param w: signal data, must be real
   :rtype: float
   :return: imaginary part of the analytic signal


.. py:function:: poissons_ratio(vp, vs)

   Calculate Poisson's Ratio based on the definition given in the Specfem3D
   source code

   :type vp: float or np.array
   :param vp: P-wave velocity
   :type vs: float or np.array
   :param vs: S-wave velocity
   :rtype: float or np.array
   :return: Poissons ratio


.. py:function:: parabolic_backtrack(f0, g0, x1, f1, b1=0.1, b2=0.5)

   Safeguarded parabolic backtracking function
   Equation provided in Nocedal & Wright, 2006 ??

   :type f0: float
   :param f0: initial misfit function value
   :type g0: float
   :param g0: slope
   :type x1: float
   :param x1: step length value
   :type f1: float
   :param f1: current misfit function value (?)
   :type b1: float
   :param b1: constant for safeguard
   :type b2: float
   :param b2: constant for safeguard
   :rtype: float
   :return: trial step length (alpha)


.. py:function:: gaussian(x, y, mu, sigma, normalize=True)

   Evaluates Gaussian over points of X, Y

   :type x: np.ndarray
   :param x: x-axis to evaluate gaussian over
   :type y: np.ndarray
   :param y: y-axis to evaluate gaussian over
   :type mu: ???
   :param mu: expected value
   :type sigma: ???
   :param sigma: standard deviation
   :type normalize: bool
   :param normalize: normalize the results


.. py:function:: polynomial_fit(x, f)

   Least squares (polynomial) line fitting used to fit a line to the
   objective function.

   :type x: np.array
   :param x: trial step lengths
   :type f: np.array
   :param f: misfit values
   :rtype: float
   :return: trial step length (alpha)


.. py:function:: lsq2(x, f)

   Parabolic least squares fit

   :type x: np.array
   :param x: x coordinates
   :type f: np.array
   :param f: y coordinates


.. py:function:: nabla(V, h=[])

   Finite Differences

   Returns sum of first-order spatial derivatives of a function defined on
   a 2D rectangular grid; generalizes Laplacian


.. py:function:: nabla2(V, h=[])

   Finite Differences

   Returns sum of second-order spatial derivatives of a function defined on
   a 2D rectangular grid; generalizes Laplacian


.. py:function:: grad(V, h=[])

   Finite Differences

   Evaluates derivatives on a 2D rectangular grid


.. py:function:: tv(Z, h=[], epsilon=1e-06)

   Finite Differences