API Documentation¶
General quadrature method for Hankel transformations.
Based on the algorithm provided in H. Ogata, A Numerical Integration Formula Based on the Bessel Functions, Publications of the Research Institute for Mathematical Sciences, vol. 41, no. 4, pp. 949-970, 2005.
Classes¶
|
The basis of the Hankel Transformation algorithm by Ogata 2005. |
|
Fourier Transform of a radially symmetric function in arbitrary dimensions. |
Functions¶
|
Determine the largest value of h which gives a converged solution. |
-
class
hankel.HankelTransform(nu=0, N=None, h=0.05, alt=False)[source]¶ The basis of the Hankel Transformation algorithm by Ogata 2005.
This algorithm is used to solve the equation \(\int_0^\infty f(x) J_\nu(x) dx\) where \(J_\nu(x)\) is a Bessel function of the first kind of order \(\nu\), and \(f(x)\) is an arbitrary (slowly-decaying) function.
The algorithm is presented in H. Ogata, A Numerical Integration Formula Based on the Bessel Functions, Publications of the Research Institute for Mathematical Sciences, vol. 41, no. 4, pp. 949-970, 2005.
This class provides a method for directly performing this integration, and also for doing a Hankel Transform.
- Parameters
nu (scalar, optional) – The order of the bessel function (of the first kind) J_nu(x)
N (int, optional, default =
pi/h) – The number of nodes in the calculation. Generally this must increase for a smaller value of the step-size h. Default value is based on where the series will truncate according to the double-exponential convergence to the roots of the Bessel function.h (float, optional) – The step-size of the integration.
alt (bool, optional) – Whether to use the alternative definition of the hankel transform. should be used. Default: False
-
classmethod
G(f, h, k=None, *args, **kwargs)[source]¶ Alias of
final_term_amplitude().Deprecated since version Deprecated: as of v1. Will be removed in v1.2.
-
classmethod
deltaG(f, h, *args, **kwargs)[source]¶ Alias of
slope_of_last_term().Deprecated since version Deprecated: as of v1. Will be removed in v1.2.
-
classmethod
final_term_amplitude(f, h, k=None, *args, **kwargs)[source]¶ Get the amplitude of the last term in cumulative sum.
The absolute value of the non-oscillatory component of the summed series’ last term, up to a scaling constant. This can be used to get the sign of the slope of the amplitude with h.
- Parameters
- Returns
The value of G, the amplitude of the final term in the series’ sum.
- Return type
-
integrate(self, f, ret_err=True, ret_cumsum=False)[source]¶ Do the Hankel-type integral of the function f.
This is not the Hankel transform, but rather the simplified integral, \(\int_0^\infty f(x) J_\nu(x) dx\) , equivalent to the transform of \(f(r)/r\) at k=1.
- Parameters
f (callable) – A function of one variable, representing \(f(x)\)
ret_err (boolean, optional, default = True) – Whether to return the estimated error
ret_cumsum (boolean, optional, default = False) – Whether to return the cumulative sum
- Returns
ret (float) – The Hankel integral of f(x).
err (float) – The estimated error of the approximate integral. It is merely the last term in the sum. Only returned if ret_err=True.
cumsum (array-like) – The total cumulative sum, for which the last term is itself the integral. One can use this to check whether the integral is converging. Only returned if ret_cumsum=True
See also
transform()The Hankel transform (this function calls
transform()withk=1andf(x) = f(x)/x.
-
property
nu¶ Order of the hankel transform.
-
classmethod
slope_of_last_term(f, h, *args, **kwargs)[source]¶ Get the slope (up to a constant) of the last term of the series with h.
- Parameters
f (callable) – The function to integrate/transform
h (float) – The resolution parameter of the hankel integration
- Other Parameters
args, kwargs – All other parameters are passed through to
final_term_amplitude().- Returns
The derivative of the last term of the series with h.
- Return type
-
transform(self, f, k=1, ret_err=True, ret_cumsum=False, inverse=False)[source]¶ Do the Hankel-transform of the function f.
- Parameters
f (callable) – A function of one variable, representing \(f(x)\)
ret_err (boolean, optional, default = True) – Whether to return the estimated error
ret_cumsum (boolean, optional, default = False) – Whether to return the cumulative sum
- Returns
ret (array-like) – The Hankel-transform of f(x) at the provided k. If k is scalar, then this will be scalar.
err (array-like) – The estimated error of the approximate integral, at every k. It is merely the last term in the sum. Only returned if ret_err=True.
cumsum (array-like) – The total cumulative sum, for which the last term is itself the transform. One can use this to check whether the integral is converging. Only returned if ret_cumsum=True
Notes
The Hankel transform is defined as
\[F(k) = \int_0^\infty r f(r) J_\nu(kr) dr.\]Or in the alternative case with
alt=True:\[F(k) = \int_0^\infty f(r) \sqrt{kr} J_\nu(kr) dr.\]The inverse transform is identical (swapping k and r of course).
-
xrange(self, k=1)[source]¶ Tuple giving (min,max) x value evaluated by f(x).
- Parameters
k (array-like, optional) – Scales for the transformation. Leave as 1 for an integral.
See also
xrange_approx()An approximate version of this method which is a classmethod.
-
class
hankel.SymmetricFourierTransform(ndim=2, a=1, b=1, N=None, h=0.05, alt=True)[source]¶ Fourier Transform of a radially symmetric function in arbitrary dimensions.
- Parameters
ndim (int) – Number of dimensions the transform is in.
b (a,) – This pair of values defines the Fourier convention used (see Notes below for details)
N (int, optional) – The number of nodes in the calculation. Generally this must increase for a smaller value of the step-size h.
h (float, optional) – The step-size of the integration.
alt (bool, optional) – State if the alternative definition of the hankel transform should be used. Default: False
Notes
We allow for arbitrary Fourier convention, according to the scheme in http://mathworld.wolfram.com/FourierTransform.html. That is, we define the forward and inverse n-dimensional transforms respectively as
\[F(k) = \sqrt{\frac{|b|}{(2\pi)^{1-a}}}^n \int f(r) e^{i b\mathbf{k}\cdot\mathbf{r}} d^n\mathbf{r}\]and
\[f(r) = \sqrt{\frac{|b|}{(2\pi)^{1+a}}}^n \int F(k) e^{-i b\mathbf{k}\cdot\mathbf{r}} d^n \mathbf{k}.\]By default, we set both a and b to 1, so that the forward transform has a normalisation of unity.
In this general sense, the forward and inverse Hankel transforms are respectively
\[F(k) = \sqrt{\frac{|b|}{(2\pi)^{1-a}}}^n \frac{(2\pi)^{n/2}}{(bk)^{n/2-1}} \int_0^\infty r^{n/2-1} f(r) J_{n/2-1}(bkr) r dr\]and
\[f(r) = \sqrt{\frac{|b|}{(2\pi)^{1+a}}}^n \frac{(2\pi)^{n/2}}{(br)^{n/2-1}} \int_0^\infty k^{n/2-1} f(k) J_{n/2-1}(bkr) k dk.\]-
classmethod
G(f, h, k=None, ndim=2)[source]¶ Info about the last term in the series.
Deprecated since version Deprecated: as of v1. Will be removed in v1.2.
-
classmethod
final_term_amplitude(f, h, k=None, ndim=2)[source]¶ Get the amplitude of the last term in cumulative sum.
The absolute value of the non-oscillatory component of the summed series’ last term, up to a scaling constant. This can be used to get the sign of the slope of the amplitude with h.
- Parameters
- Returns
The amplitude of the final term in the sum.
- Return type
-
hankel.get_h(f, nu, K=None, cls=None, hstart=0.05, hdecrement=2, atol=0.001, rtol=0.001, maxiter=15, inverse=False)[source]¶ Determine the largest value of h which gives a converged solution.
- Parameters
f (callable) – The function to be integrated/transformed.
nu (float) – Either the order of the transformation, or the number of dimensions (if cls is a
SymmetricFourierTransform)K (float or array-like, optional) – The scale(s) of the transformation. If None, assumes an integration over f(x)J_nu(x) is desired. It is recommended to use a down-sampled K for this routine for efficiency. Often a min/max is enough.
cls (
HankelTransformsubclass, optional) – EitherHankelTransformor a subclass, specifying the type of transformation to do on f.hstart (float, optional) – The starting value of h.
hdecrement (float, optional) – How much to divide h by on each iteration.
rtol (atol,) – The tolerance parameters, passed to np.isclose, defining the stopping condition.
maxiter (int, optional) – Maximum number of iterations to perform.
inverse (bool, optional) – Whether to treat as an inverse transformation.
- Returns
h (float) – The h value at which the solution converges.
res (scalar or tuple) – The value of the integral/transformation using the returned h – if a transformation, returns results at K.
N (int) – The number of nodes necessary in the final calculation. While each iteration uses N=pi/h, the returned N checks whether nodes are numerically zero above some threshold.
Notes
This function is not completely general. The function f is assumed to be reasonably smooth and non-oscillatory.
The idea is to use successively smaller values of h, with N=pi/h on each iteration, until the result betweeniterations becomes stable.