"""
========================================
Special functions (:mod:`scipy.special`)
========================================

.. module:: scipy.special

Nearly all of the functions below are universal functions and follow
broadcasting and automatic array-looping rules. Exceptions are noted.

Error handling
==============

Errors are handled by returning nans, or other appropriate values.
Some of the special function routines will emit warnings when an error
occurs.  By default this is disabled.  To enable such messages use
``errprint(1)``, and to disable such messages use ``errprint(0)``.

Example:

    >>> print scipy.special.bdtr(-1,10,0.3)
    >>> scipy.special.errprint(1)
    >>> print scipy.special.bdtr(-1,10,0.3)

.. autosummary::
   :toctree: generated/

   errprint
   SpecialFunctionWarning -- Warning that can be issued with ``errprint(True)``

Available functions
===================

Airy functions
--------------

.. autosummary::
   :toctree: generated/

   airy     -- Airy functions and their derivatives.
   airye    -- Exponentially scaled Airy functions
   ai_zeros -- [+]Zeros of Airy functions Ai(x) and Ai'(x)
   bi_zeros -- [+]Zeros of Airy functions Bi(x) and Bi'(x)
   itairy   --
   

Elliptic Functions and Integrals
--------------------------------

.. autosummary::
   :toctree: generated/

   ellipj    -- Jacobian elliptic functions
   ellipk    -- Complete elliptic integral of the first kind.
   ellipkm1  -- ellipkm1(x) == ellipk(1 - x)
   ellipkinc -- Incomplete elliptic integral of the first kind.
   ellipe    -- Complete elliptic integral of the second kind.
   ellipeinc -- Incomplete elliptic integral of the second kind.

Bessel Functions
----------------

.. autosummary::
   :toctree: generated/

   jv       -- Bessel function of real-valued order and complex argument.
   jn       -- Alias for jv
   jve      -- Exponentially scaled Bessel function.
   yn       -- Bessel function of second kind (integer order).
   yv       -- Bessel function of the second kind (real-valued order).
   yve      -- Exponentially scaled Bessel function of the second kind.
   kn       -- Modified Bessel function of the second kind (integer order).
   kv       -- Modified Bessel function of the second kind (real order).
   kve      -- Exponentially scaled modified Bessel function of the second kind.
   iv       -- Modified Bessel function.
   ive      -- Exponentially scaled modified Bessel function.
   hankel1  -- Hankel function of the first kind.
   hankel1e -- Exponentially scaled Hankel function of the first kind.
   hankel2  -- Hankel function of the second kind.
   hankel2e -- Exponentially scaled Hankel function of the second kind.

The following is not an universal function:

.. autosummary::
   :toctree: generated/

   lmbda       -- [+]Sequence of lambda functions with arbitrary order v.

Zeros of Bessel Functions
^^^^^^^^^^^^^^^^^^^^^^^^^

These are not universal functions:

.. autosummary::
   :toctree: generated/

   jnjnp_zeros -- [+]Zeros of integer-order Bessel functions and derivatives sorted in order.
   jnyn_zeros  -- [+]Zeros of integer-order Bessel functions and derivatives as separate arrays.
   jn_zeros    -- [+]Zeros of Jn(x)
   jnp_zeros   -- [+]Zeros of Jn'(x)
   yn_zeros    -- [+]Zeros of Yn(x)
   ynp_zeros   -- [+]Zeros of Yn'(x)
   y0_zeros    -- [+]Complex zeros: Y0(z0)=0 and values of Y0'(z0)
   y1_zeros    -- [+]Complex zeros: Y1(z1)=0 and values of Y1'(z1)
   y1p_zeros   -- [+]Complex zeros of Y1'(z1')=0 and values of Y1(z1')

Faster versions of common Bessel Functions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autosummary::
   :toctree: generated/

   j0       -- Bessel function of order 0.
   j1       -- Bessel function of order 1.
   y0       -- Bessel function of second kind of order 0.
   y1       -- Bessel function of second kind of order 1.
   i0       -- Modified Bessel function of order 0.
   i0e      -- Exponentially scaled modified Bessel function of order 0.
   i1       -- Modified Bessel function of order 1.
   i1e      -- Exponentially scaled modified Bessel function of order 1.
   k0       -- Modified Bessel function of the second kind of order 0.
   k0e      -- Exponentially scaled modified Bessel function of the second kind of order 0.
   k1       -- Modified Bessel function of the second kind of order 1.
   k1e      -- Exponentially scaled modified Bessel function of the second kind of order 1.

Integrals of Bessel Functions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autosummary::
   :toctree: generated/

   itj0y0     -- Basic integrals of j0 and y0 from 0 to x.
   it2j0y0    -- Integrals of (1-j0(t))/t from 0 to x and y0(t)/t from x to inf.
   iti0k0     -- Basic integrals of i0 and k0 from 0 to x.
   it2i0k0    -- Integrals of (i0(t)-1)/t from 0 to x and k0(t)/t from x to inf.
   besselpoly -- Integral of a Bessel function: Jv(2* a* x) * x[+]lambda from x=0 to 1.

Derivatives of Bessel Functions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autosummary::
   :toctree: generated/

   jvp     -- Nth derivative of Jv(v,z)
   yvp     -- Nth derivative of Yv(v,z)
   kvp     -- Nth derivative of Kv(v,z)
   ivp     -- Nth derivative of Iv(v,z)
   h1vp    -- Nth derivative of H1v(v,z)
   h2vp    -- Nth derivative of H2v(v,z)

Spherical Bessel Functions
^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autosummary::
   :toctree: generated/

   spherical_jn -- Spherical Bessel function of the first kind, jn(z)
   spherical_yn -- Spherical Bessel function of the second kind, yn(z)
   spherical_in -- Modified spherical Bessel function of the first kind, in(z)
   spherical_kn -- Modified spherical Bessel function of the second kind, kn(z)

These are not universal functions:

.. autosummary::
   :toctree: generated/

   sph_jn   -- [+]Sequence of spherical Bessel functions, jn(z)
   sph_yn   -- [+]Sequence of spherical Bessel functions, yn(z)
   sph_jnyn -- [+]Sequence of spherical Bessel functions, jn(z) and yn(z)
   sph_in   -- [+]Sequence of spherical Bessel functions, in(z)
   sph_kn   -- [+]Sequence of spherical Bessel functions, kn(z)
   sph_inkn -- [+]Sequence of spherical Bessel functions, in(z) and kn(z)

Riccati-Bessel Functions
^^^^^^^^^^^^^^^^^^^^^^^^

These are not universal functions:

.. autosummary::
   :toctree: generated/

   riccati_jn -- [+]Sequence of Ricatti-Bessel functions of first kind.
   riccati_yn -- [+]Sequence of Ricatti-Bessel functions of second kind.

Struve Functions
----------------

.. autosummary::
   :toctree: generated/

   struve       -- Struve function --- Hv(x)
   modstruve    -- Modified Struve function --- Lv(x)
   itstruve0    -- Integral of H0(t) from 0 to x
   it2struve0   -- Integral of H0(t)/t from x to Inf.
   itmodstruve0 -- Integral of L0(t) from 0 to x.


Raw Statistical Functions
-------------------------

.. seealso:: :mod:`scipy.stats`: Friendly versions of these functions.

.. autosummary::
   :toctree: generated/

   bdtr       -- Sum of terms 0 through k of the binomial pdf.
   bdtrc      -- Sum of terms k+1 through n of the binomial pdf.
   bdtri      -- Inverse of bdtr
   bdtrik     --
   bdtrin     --
   btdtr      -- Integral from 0 to x of beta pdf.
   btdtri     -- Quantiles of beta distribution
   btdtria    --
   btdtrib    --
   fdtr       -- Integral from 0 to x of F pdf.
   fdtrc      -- Integral from x to infinity under F pdf.
   fdtri      -- Inverse of fdtrc
   fdtridfd   -- 
   gdtr       -- Integral from 0 to x of gamma pdf.
   gdtrc      -- Integral from x to infinity under gamma pdf.
   gdtria     -- Inverse with respect to `a` of gdtr.
   gdtrib     -- Inverse with respect to `b` of gdtr.
   gdtrix     -- Inverse with respect to `x` of gdtr.
   nbdtr      -- Sum of terms 0 through k of the negative binomial pdf.
   nbdtrc     -- Sum of terms k+1 to infinity under negative binomial pdf.
   nbdtri     -- Inverse of nbdtr
   nbdtrik    --
   nbdtrin    --
   ncfdtr     -- CDF of non-central t distribution.
   ncfdtridfd -- Find degrees of freedom (denominator) of noncentral F distribution.
   ncfdtridfn -- Find degrees of freedom (numerator) of noncentral F distribution.
   ncfdtri    -- Inverse CDF of noncentral F distribution.
   ncfdtrinc  -- Find noncentrality parameter of noncentral F distribution.
   nctdtr     -- CDF of noncentral t distribution.
   nctdtridf  -- Find degrees of freedom of noncentral t distribution.
   nctdtrit   -- Inverse CDF of noncentral t distribution.
   nctdtrinc  -- Find noncentrality parameter of noncentral t distribution.
   nrdtrimn   -- Find mean of normal distribution from cdf and std.
   nrdtrisd   -- Find std of normal distribution from cdf and mean.
   pdtr       -- Sum of terms 0 through k of the Poisson pdf.
   pdtrc      -- Sum of terms k+1 to infinity of the Poisson pdf.
   pdtri      -- Inverse of pdtr
   pdtrik     --
   stdtr      -- Integral from -infinity to t of the Student-t pdf.
   stdtridf   --
   stdtrit    --
   chdtr      -- Integral from 0 to x of the Chi-square pdf.
   chdtrc     -- Integral from x to infnity of Chi-square pdf.
   chdtri     -- Inverse of chdtrc.
   chdtriv    --
   ndtr       -- Integral from -infinity to x of standard normal pdf
   log_ndtr   -- Logarithm of integral from -infinity to x of standard normal pdf
   ndtri      -- Inverse of ndtr (quantiles)
   chndtr     --
   chndtridf  --
   chndtrinc  --
   chndtrix   --
   smirnov    -- Kolmogorov-Smirnov complementary CDF for one-sided test statistic (Dn+ or Dn-)
   smirnovi   -- Inverse of smirnov.
   kolmogorov -- The complementary CDF of the (scaled) two-sided test statistic (Kn*) valid for large n.
   kolmogi    -- Inverse of kolmogorov
   tklmbda    -- Tukey-Lambda CDF
   logit      --
   expit      --
   boxcox     -- Compute the Box-Cox transformation.
   boxcox1p   -- Compute the Box-Cox transformation of 1 + x.
   inv_boxcox -- Compute the inverse of the Box-Cox tranformation.
   inv_boxcox1p -- Compute the inverse of the Box-Cox transformation of 1 + x.


Information Theory Functions
----------------------------

.. autosummary::
   :toctree: generated/

   entr         -- entr(x) = -x*log(x)
   rel_entr     -- rel_entr(x, y) = x*log(x/y)
   kl_div       -- kl_div(x, y) = x*log(x/y) - x + y
   huber        -- Huber loss function.
   pseudo_huber -- Pseudo-Huber loss function.


Gamma and Related Functions
---------------------------

.. autosummary::
   :toctree: generated/

   gamma        -- Gamma function.
   gammaln      -- Log of the absolute value of the Gamma function.
   loggamma     -- Principal branch of the logarithm of the Gamma function.
   gammasgn     -- Sign of the gamma function.
   gammainc     -- Incomplete gamma integral.
   gammaincinv  -- Inverse of gammainc.
   gammaincc    -- Complemented incomplete gamma integral.
   gammainccinv -- Inverse of gammaincc.
   beta         -- Beta function.
   betaln       -- Log of the absolute value of the beta function.
   betainc      -- Incomplete beta integral.
   betaincinv   -- Inverse of betainc.
   psi          -- Logarithmic derivative of the gamma function.
   rgamma       -- One divided by the gamma function.
   polygamma    -- Nth derivative of psi function.
   multigammaln -- Log of the multivariate gamma.
   digamma      -- Digamma function (derivative of the logarithm of gamma).
   poch         -- The Pochhammer symbol (rising factorial).


Error Function and Fresnel Integrals
------------------------------------

.. autosummary::
   :toctree: generated/

   erf           -- Error function.
   erfc          -- Complemented error function (1- erf(x))
   erfcx         -- Scaled complemented error function exp(x**2)*erfc(x)
   erfi          -- Imaginary error function, -i erf(i x)
   erfinv        -- Inverse of error function
   erfcinv       -- Inverse of erfc
   wofz          -- Fadeeva function.
   dawsn         -- Dawson's integral.
   fresnel       -- Fresnel sine and cosine integrals.
   fresnel_zeros -- Complex zeros of both Fresnel integrals
   modfresnelp   -- Modified Fresnel integrals F_+(x) and K_+(x)
   modfresnelm   -- Modified Fresnel integrals F_-(x) and K_-(x)

These are not universal functions:

.. autosummary::
   :toctree: generated/

   erf_zeros      -- [+]Complex zeros of erf(z)
   fresnelc_zeros -- [+]Complex zeros of Fresnel cosine integrals
   fresnels_zeros -- [+]Complex zeros of Fresnel sine integrals

Legendre Functions
------------------

.. autosummary::
   :toctree: generated/

   lpmv     -- Associated Legendre Function of arbitrary non-negative degree v.
   sph_harm -- Spherical Harmonics (complex-valued) Y^m_n(theta,phi)

These are not universal functions:

.. autosummary::
   :toctree: generated/

   clpmn    -- [+]Associated Legendre Function of the first kind for complex arguments.
   lpn      -- [+]Legendre Functions (polynomials) of the first kind
   lqn      -- [+]Legendre Functions of the second kind.
   lpmn     -- [+]Associated Legendre Function of the first kind for real arguments.
   lqmn     -- [+]Associated Legendre Function of the second kind.

Ellipsoidal Harmonics
---------------------

.. autosummary::
   :toctree: generated/

   ellip_harm    -- Ellipsoidal harmonic E
   ellip_harm_2  -- Ellipsoidal harmonic F
   ellip_normal  -- Ellipsoidal normalization constant

Orthogonal polynomials
----------------------

The following functions evaluate values of orthogonal polynomials:

.. autosummary::
   :toctree: generated/

   assoc_laguerre
   eval_legendre
   eval_chebyt
   eval_chebyu
   eval_chebyc
   eval_chebys
   eval_jacobi
   eval_laguerre
   eval_genlaguerre
   eval_hermite
   eval_hermitenorm
   eval_gegenbauer
   eval_sh_legendre
   eval_sh_chebyt
   eval_sh_chebyu
   eval_sh_jacobi

The functions below, in turn, return the polynomial coefficients in
:class:`~.orthopoly1d` objects, which function similarly as :ref:`numpy.poly1d`.
The :class:`~.orthopoly1d` class also has an attribute ``weights`` which returns
the roots, weights, and total weights for the appropriate form of Gaussian
quadrature.  These are returned in an ``n x 3`` array with roots in the first
column, weights in the second column, and total weights in the final column.
Note that :class:`~.orthopoly1d` objects are converted to ``poly1d`` when doing
arithmetic, and lose information of the original orthogonal polynomial.

.. autosummary::
   :toctree: generated/

   legendre    -- [+]Legendre polynomial P_n(x) (lpn -- for function).
   chebyt      -- [+]Chebyshev polynomial T_n(x)
   chebyu      -- [+]Chebyshev polynomial U_n(x)
   chebyc      -- [+]Chebyshev polynomial C_n(x)
   chebys      -- [+]Chebyshev polynomial S_n(x)
   jacobi      -- [+]Jacobi polynomial P^(alpha,beta)_n(x)
   laguerre    -- [+]Laguerre polynomial, L_n(x)
   genlaguerre -- [+]Generalized (Associated) Laguerre polynomial, L^alpha_n(x)
   hermite     -- [+]Hermite polynomial H_n(x)
   hermitenorm -- [+]Normalized Hermite polynomial, He_n(x)
   gegenbauer  -- [+]Gegenbauer (Ultraspherical) polynomials, C^(alpha)_n(x)
   sh_legendre -- [+]shifted Legendre polynomial, P*_n(x)
   sh_chebyt   -- [+]shifted Chebyshev polynomial, T*_n(x)
   sh_chebyu   -- [+]shifted Chebyshev polynomial, U*_n(x)
   sh_jacobi   -- [+]shifted Jacobi polynomial, J*_n(x) = G^(p,q)_n(x)

.. warning::

   Computing values of high-order polynomials (around ``order > 20``) using
   polynomial coefficients is numerically unstable. To evaluate polynomial
   values, the ``eval_*`` functions should be used instead.

Roots and weights for orthogonal polynomials

.. autosummary::
   :toctree: generated/

   c_roots
   cg_roots
   h_roots
   he_roots
   j_roots
   js_roots
   l_roots
   la_roots
   p_roots
   ps_roots
   s_roots
   t_roots
   ts_roots
   u_roots
   us_roots


Hypergeometric Functions
------------------------

.. autosummary::
   :toctree: generated/

   hyp2f1   -- Gauss hypergeometric function (2F1)
   hyp1f1   -- Confluent hypergeometric function (1F1)
   hyperu   -- Confluent hypergeometric function (U)
   hyp0f1   -- Confluent hypergeometric limit function (0F1)
   hyp2f0   -- Hypergeometric function (2F0)
   hyp1f2   -- Hypergeometric function (1F2)
   hyp3f0   -- Hypergeometric function (3F0)


Parabolic Cylinder Functions
----------------------------

.. autosummary::
   :toctree: generated/

   pbdv     -- Parabolic cylinder function Dv(x) and derivative.
   pbvv     -- Parabolic cylinder function Vv(x) and derivative.
   pbwa     -- Parabolic cylinder function W(a,x) and derivative.

These are not universal functions:

.. autosummary::
   :toctree: generated/

   pbdv_seq -- [+]Sequence of parabolic cylinder functions Dv(x)
   pbvv_seq -- [+]Sequence of parabolic cylinder functions Vv(x)
   pbdn_seq -- [+]Sequence of parabolic cylinder functions Dn(z), complex z

Mathieu and Related Functions
-----------------------------

.. autosummary::
   :toctree: generated/

   mathieu_a       -- Characteristic values for even solution (ce_m)
   mathieu_b       -- Characteristic values for odd solution (se_m)

These are not universal functions:

.. autosummary::
   :toctree: generated/

   mathieu_even_coef -- [+]sequence of expansion coefficients for even solution
   mathieu_odd_coef  -- [+]sequence of expansion coefficients for odd solution

The following return both function and first derivative:

.. autosummary::
   :toctree: generated/

   mathieu_cem     -- Even Mathieu function
   mathieu_sem     -- Odd Mathieu function
   mathieu_modcem1 -- Even modified Mathieu function of the first kind
   mathieu_modcem2 -- Even modified Mathieu function of the second kind
   mathieu_modsem1 -- Odd modified Mathieu function of the first kind
   mathieu_modsem2 -- Odd modified Mathieu function of the second kind

Spheroidal Wave Functions
-------------------------

.. autosummary::
   :toctree: generated/

   pro_ang1   -- Prolate spheroidal angular function of the first kind
   pro_rad1   -- Prolate spheroidal radial function of the first kind
   pro_rad2   -- Prolate spheroidal radial function of the second kind
   obl_ang1   -- Oblate spheroidal angular function of the first kind
   obl_rad1   -- Oblate spheroidal radial function of the first kind
   obl_rad2   -- Oblate spheroidal radial function of the second kind
   pro_cv     -- Compute characteristic value for prolate functions
   obl_cv     -- Compute characteristic value for oblate functions
   pro_cv_seq -- Compute sequence of prolate characteristic values
   obl_cv_seq -- Compute sequence of oblate characteristic values

The following functions require pre-computed characteristic value:

.. autosummary::
   :toctree: generated/

   pro_ang1_cv -- Prolate spheroidal angular function of the first kind
   pro_rad1_cv -- Prolate spheroidal radial function of the first kind
   pro_rad2_cv -- Prolate spheroidal radial function of the second kind
   obl_ang1_cv -- Oblate spheroidal angular function of the first kind
   obl_rad1_cv -- Oblate spheroidal radial function of the first kind
   obl_rad2_cv -- Oblate spheroidal radial function of the second kind

Kelvin Functions
----------------

.. autosummary::
   :toctree: generated/

   kelvin       -- All Kelvin functions (order 0) and derivatives.
   kelvin_zeros -- [+]Zeros of All Kelvin functions (order 0) and derivatives
   ber          -- Kelvin function ber x
   bei          -- Kelvin function bei x
   berp         -- Derivative of Kelvin function ber x
   beip         -- Derivative of Kelvin function bei x
   ker          -- Kelvin function ker x
   kei          -- Kelvin function kei x
   kerp         -- Derivative of Kelvin function ker x
   keip         -- Derivative of Kelvin function kei x

These are not universal functions:

.. autosummary::
   :toctree: generated/

   ber_zeros    -- [+]Zeros of Kelvin function bei x
   bei_zeros    -- [+]Zeros of Kelvin function ber x
   berp_zeros   -- [+]Zeros of derivative of Kelvin function ber x
   beip_zeros   -- [+]Zeros of derivative of Kelvin function bei x
   ker_zeros    -- [+]Zeros of Kelvin function kei x
   kei_zeros    -- [+]Zeros of Kelvin function ker x
   kerp_zeros   -- [+]Zeros of derivative of Kelvin function ker x
   keip_zeros   -- [+]Zeros of derivative of Kelvin function kei x

Combinatorics
-------------

.. autosummary::
   :toctree: generated/

   comb    -- [+]Combinations of N things taken k at a time, "N choose k"
   perm    -- [+]Permutations of N things taken k at a time, "k-permutations of N"

Other Special Functions
-----------------------

.. autosummary::
   :toctree: generated/

   agm          -- Arithmetic-Geometric Mean
   bernoulli    -- Bernoulli numbers
   binom        -- Binomial coefficient.
   diric        -- Dirichlet function (periodic sinc)
   euler        -- Euler numbers
   expn         -- Exponential integral.
   exp1         -- Exponential integral of order 1 (for complex argument)
   expi         -- Another exponential integral -- Ei(x)
   factorial    -- The factorial function, n! = special.gamma(n+1)
   factorial2   -- Double factorial, (n!)!
   factorialk   -- [+](...((n!)!)!...)! where there are k '!'
   shichi       -- Hyperbolic sine and cosine integrals.
   sici         -- Integral of the sinc and "cosinc" functions.
   spence       -- Spence's function, also known as the dilogarithm.
   lambertw     -- Lambert W function
   zeta         -- Riemann zeta function of two arguments.
   zetac        -- Standard Riemann zeta function minus 1.

Convenience Functions
---------------------

.. autosummary::
   :toctree: generated/

   cbrt     -- Cube root.
   exp10    -- 10 raised to the x power.
   exp2     -- 2 raised to the x power.
   radian   -- radian angle given degrees, minutes, and seconds.
   cosdg    -- cosine of the angle given in degrees.
   sindg    -- sine of the angle given in degrees.
   tandg    -- tangent of the angle given in degrees.
   cotdg    -- cotangent of the angle given in degrees.
   log1p    -- log(1+x)
   expm1    -- exp(x)-1
   cosm1    -- cos(x)-1
   round    -- round the argument to the nearest integer. If argument ends in 0.5 exactly, pick the nearest even integer.
   xlogy    -- x*log(y)
   xlog1py  -- x*log1p(y)
   exprel   -- (exp(x)-1)/x
   sinc     -- sin(x)/x

.. [+] in the description indicates a function which is not a universal
.. function and does not follow broadcasting and automatic
.. array-looping rules.

"""

from __future__ import division, print_function, absolute_import

from ._ufuncs import *

from .basic import *
from . import specfun
from . import orthogonal
from .orthogonal import *
from .spfun_stats import multigammaln
from ._ellip_harm import ellip_harm, ellip_harm_2, ellip_normal
from .lambertw import lambertw
from ._spherical_bessel import (spherical_jn, spherical_yn, spherical_in,
                                spherical_kn)

__all__ = [s for s in dir() if not s.startswith('_')]

from numpy.dual import register_func
register_func('i0',i0)
del register_func

from numpy.testing import Tester
test = Tester().test