-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Special functions and Chebyshev polynomials
--   
--   This library provides implementations of special mathematical
--   functions and Chebyshev polynomials. These functions are often useful
--   in statistical and numerical computing.
--   
--   Changes in 0.1.2
--   
--   <ul>
--   <li>Error function and its inverse added.</li>
--   <li>Digamma function added</li>
--   <li>Evaluation of polynomials using Horner's method added.</li>
--   <li>Crash bug in the inverse incomplete beta fixed.</li>
--   </ul>
@package math-functions
@version 0.1.3.0


-- | Constant values common to much numeric code.
module Numeric.MathFunctions.Constants

-- | The smallest <a>Double</a> ε such that 1 + ε ≠ 1.
m_epsilon :: Double

-- | A very large number.
m_huge :: Double
m_tiny :: Double

-- | The largest <a>Int</a> <i>x</i> such that 2**(<i>x</i>-1) is
--   approximately representable as a <a>Double</a>.
m_max_exp :: Int

-- | Positive infinity.
m_pos_inf :: Double

-- | Negative infinity.
m_neg_inf :: Double

-- | Not a number.
m_NaN :: Double

-- | <pre>
--   1 / sqrt 2
--   </pre>
m_1_sqrt_2 :: Double

-- | <pre>
--   2 / sqrt pi
--   </pre>
m_2_sqrt_pi :: Double

-- | <pre>
--   log(sqrt((2*pi))
--   </pre>
m_ln_sqrt_2_pi :: Double

-- | <pre>
--   sqrt 2
--   </pre>
m_sqrt_2 :: Double

-- | <pre>
--   sqrt (2 * pi)
--   </pre>
m_sqrt_2_pi :: Double

-- | Euler–Mascheroni constant (γ = 0.57721...)
m_eulerMascheroni :: Double


-- | Less common mathematical functions.
module Numeric.SpecFunctions.Extra

-- | Evaluate the deviance term <tt>x log(x/np) + np - x</tt>.
bd0 :: Double -> Double -> Double


-- | Chebyshev polynomials.
module Numeric.Polynomial.Chebyshev

-- | Evaluate a Chebyshev polynomial of the first kind. Uses Clenshaw's
--   algorithm.
chebyshev :: Vector v Double => Double -> v Double -> Double

-- | Evaluate a Chebyshev polynomial of the first kind. Uses Broucke's
--   ECHEB algorithm, and his convention for coefficient handling. It treat
--   0th coefficient different so
--   
--   <pre>
--   chebyshev x [a0,a1,a2...] == chebyshevBroucke [2*a0,a1,a2...]
--   </pre>
chebyshevBroucke :: Vector v Double => Double -> v Double -> Double


-- | Function for evaluating polynomials using Horher's method.
module Numeric.Polynomial

-- | Evaluate polynomial using Horner's method. Coefficients starts from
--   lowest. In pseudocode:
--   
--   <pre>
--   evaluateOddPolynomial x [1,2,3] = 1 + 2*x + 3*x^2
--   </pre>
evaluatePolynomial :: (Vector v a, Num a) => a -> v a -> a

-- | Evaluate polynomial with only even powers using Horner's method.
--   Coefficients starts from lowest. In pseudocode:
--   
--   <pre>
--   evaluateOddPolynomial x [1,2,3] = 1 + 2*x^2 + 3*x^4
--   </pre>
evaluateEvenPolynomial :: (Vector v a, Num a) => a -> v a -> a

-- | Evaluate polynomial with only odd powers using Horner's method.
--   Coefficients starts from lowest. In pseudocode:
--   
--   <pre>
--   evaluateOddPolynomial x [1,2,3] = 1*x + 2*x^3 + 3*x^5
--   </pre>
evaluateOddPolynomial :: (Vector v a, Num a) => a -> v a -> a


-- | Special functions and factorials.
module Numeric.SpecFunctions

-- | Error function.
--   
--   <pre>
--   erf -∞ = -1
--   erf  0 =  0
--   erf +∞ =  1
--   </pre>
erf :: Double -> Double

-- | Complementary error function.
--   
--   <pre>
--   erfc -∞ = 2
--   erfc  0 = 1
--   errc +∞ = 0
--   </pre>
erfc :: Double -> Double

-- | Inverse of <a>erf</a>.
invErf :: Double -> Double

-- | Inverse of <a>erfc</a>.
invErfc :: Double -> Double

-- | Compute the logarithm of the gamma function Γ(<i>x</i>). Uses
--   Algorithm AS 245 by Macleod.
--   
--   Gives an accuracy of 10-12 significant decimal digits, except for
--   small regions around <i>x</i> = 1 and <i>x</i> = 2, where the function
--   goes to zero. For greater accuracy, use <a>logGammaL</a>.
--   
--   Returns ∞ if the input is outside of the range (0 &lt; <i>x</i> ≤
--   1e305).
logGamma :: Double -> Double

-- | Compute the logarithm of the gamma function, Γ(<i>x</i>). Uses a
--   Lanczos approximation.
--   
--   This function is slower than <a>logGamma</a>, but gives 14 or more
--   significant decimal digits of accuracy, except around <i>x</i> = 1 and
--   <i>x</i> = 2, where the function goes to zero.
--   
--   Returns ∞ if the input is outside of the range (0 &lt; <i>x</i> ≤
--   1e305).
logGammaL :: Double -> Double

-- | Compute the normalized lower incomplete gamma function
--   γ(<i>s</i>,<i>x</i>). Normalization means that γ(<i>s</i>,∞)=1. Uses
--   Algorithm AS 239 by Shea.
incompleteGamma :: Double -> Double -> Double

-- | Inverse incomplete gamma function. It's approximately inverse of
--   <a>incompleteGamma</a> for the same <i>s</i>. So following equality
--   approximately holds:
--   
--   <pre>
--   invIncompleteGamma s . incompleteGamma s = id
--   </pre>
invIncompleteGamma :: Double -> Double -> Double

-- | Compute ψ0(<i>x</i>), the first logarithmic derivative of the gamma
--   function. Uses Algorithm AS 103 by Bernardo, based on Minka's C
--   implementation.
digamma :: Double -> Double

-- | Compute the natural logarithm of the beta function.
logBeta :: Double -> Double -> Double

-- | Regularized incomplete beta function. Uses algorithm AS63 by Majumder
--   and Bhattachrjee and quadrature approximation for large <i>p</i> and
--   <i>q</i>.
incompleteBeta :: Double -> Double -> Double -> Double

-- | Regularized incomplete beta function. Same as <a>incompleteBeta</a>
--   but also takes logarithm of beta function as parameter.
incompleteBeta_ :: Double -> Double -> Double -> Double -> Double

-- | Compute inverse of regularized incomplete beta function. Uses initial
--   approximation from AS109, AS64 and Halley method to solve equation.
invIncompleteBeta :: Double -> Double -> Double -> Double

-- | Compute the natural logarithm of 1 + <tt>x</tt>. This is accurate even
--   for values of <tt>x</tt> near zero, where use of <tt>log(1+x)</tt>
--   would lose precision.
log1p :: Double -> Double

-- | <i>O(log n)</i> Compute the logarithm in base 2 of the given value.
log2 :: Int -> Int

-- | Compute the factorial function <i>n</i>!. Returns +∞ if the input is
--   above 170 (above which the result cannot be represented by a 64-bit
--   <a>Double</a>).
factorial :: Int -> Double

-- | Compute the natural logarithm of the factorial function. Gives 16
--   decimal digits of precision.
logFactorial :: Int -> Double

-- | Calculate the error term of the Stirling approximation. This is only
--   defined for non-negative values.
--   
--   <pre>
--   stirlingError @n@ = @log(n!) - log(sqrt(2*pi*n)*(n/e)^n)
--   </pre>
stirlingError :: Double -> Double

-- | Compute the binomial coefficient <i>n</i> <tt>`<a>choose</a>`</tt>
--   <i>k</i>. For values of <i>k</i> &gt; 30, this uses an approximation
--   for performance reasons. The approximation is accurate to 12 decimal
--   places in the worst case
--   
--   Example:
--   
--   <pre>
--   7 `choose` 3 == 35
--   </pre>
choose :: Int -> Int -> Double