Class BoostErf

java.lang.Object
org.apache.commons.numbers.gamma.BoostErf

final class BoostErf extends Object
Implementation of the error function and its inverse.

This code has been adapted from the Boost c++ implementation <boost/math/special_functions/erf.hpp>. The erf/erfc functions and their inverses are copyright John Maddock 2006 and subject to the Boost Software License.

Additions made to support the erfcx function are original work under the Apache software license.

See Also:
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private static final double
    Threshold for the erf implementation for |x| where the computation uses erf(x); otherwise erfc(x) is computed.
    private static final double
    Threshold for the scaled complementary error function erfcx where the approximation (1 / sqrt(pi)) / x can be used.
    private static final double
    Threshold for the scaled complementary error function erfcx for negative x where 2 * exp(x*x) will overflow.
    private static final double
    Threshold for the scaled complementary error function erfcx for x where exp(x*x) == 1; x <= t.
    private static final double
    1 / sqrt(pi).
  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    private
    Private constructor.
  • Method Summary

    Modifier and Type
    Method
    Description
    (package private) static double
    erf(double x)
    Returns the error function.
    (package private) static double
    erfc(double x)
    Returns the complementary error function.
    (package private) static double
    erfcInv(double z)
    Returns the inverse complementary error function.
    (package private) static double
    erfcx(double x)
    Returns the scaled complementary error function.
    private static double
    erfImp(double z, boolean invert, boolean scaled)
    53-bit implementation for the error function.
    (package private) static double
    erfInv(double z)
    Returns the inverse error function.
    private static double
    erfInvImp(double p, double q)
    Common implementation for inverse erf and erfc functions.
    (package private) static double
    expmxx(double x)
    Compute exp(-x*x) with high accuracy.
    (package private) static double
    expxx(double x)
    Compute exp(x*x) with high accuracy.
    private static double
    expxx(double a, double b)
    Compute exp(a+b) with high accuracy assuming a+b = a.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Field Details

    • ONE_OVER_ROOT_PI

      private static final double ONE_OVER_ROOT_PI
      1 / sqrt(pi). Used for the scaled complementary error function erfcx.
      See Also:
    • ERFCX_APPROX

      private static final double ERFCX_APPROX
      Threshold for the scaled complementary error function erfcx where the approximation (1 / sqrt(pi)) / x can be used.
      See Also:
    • COMPUTE_ERF

      private static final double COMPUTE_ERF
      Threshold for the erf implementation for |x| where the computation uses erf(x); otherwise erfc(x) is computed. The final result is achieved by suitable application of symmetry.
      See Also:
    • ERFCX_NEG_X_MAX

      private static final double ERFCX_NEG_X_MAX
      Threshold for the scaled complementary error function erfcx for negative x where 2 * exp(x*x) will overflow. Value is 26.62873571375149.
    • EXP_XX_1

      private static final double EXP_XX_1
      Threshold for the scaled complementary error function erfcx for x where exp(x*x) == 1; x <= t. Value is (1 + 5/16) * 2^-27 = 9.778887033462524E-9.

      Note: This is used for performance. If set to 0 then the result is computed using expm1(x*x) with the same final result.

      See Also:
  • Constructor Details

    • BoostErf

      private BoostErf()
      Private constructor.
  • Method Details

    • erfc

      static double erfc(double x)
      Returns the complementary error function.
      Parameters:
      x - the value.
      Returns:
      the complementary error function.
    • erf

      static double erf(double x)
      Returns the error function.
      Parameters:
      x - the value.
      Returns:
      the error function.
    • erfImp

      private static double erfImp(double z, boolean invert, boolean scaled)
      53-bit implementation for the error function.

      Note: The scaled flag only applies when z >= 0.5 and invert == true. This functionality is used to compute erfcx(z) for positive z.

      Parameters:
      z - Point to evaluate
      invert - true to invert the result (for the complementary error function)
      scaled - true to compute the scaled complementary error function
      Returns:
      the error function result
    • erfcx

      static double erfcx(double x)
      Returns the scaled complementary error function.
       erfcx(x) = exp(x^2) * erfc(x)
       
      Parameters:
      x - the value.
      Returns:
      the scaled complementary error function.
    • erfcInv

      static double erfcInv(double z)
      Returns the inverse complementary error function.
      Parameters:
      z - Value (in [0, 2]).
      Returns:
      t such that z = erfc(t)
    • erfInv

      static double erfInv(double z)
      Returns the inverse error function.
      Parameters:
      z - Value (in [-1, 1]).
      Returns:
      t such that z = erf(t)
    • erfInvImp

      private static double erfInvImp(double p, double q)
      Common implementation for inverse erf and erfc functions.
      Parameters:
      p - P-value
      q - Q-value (1-p)
      Returns:
      the inverse
    • expxx

      static double expxx(double x)
      Compute exp(x*x) with high accuracy. This is performed using information in the round-off from x*x.

      This is accurate at large x to 1 ulp.

      At small x the accuracy cannot be improved over using exp(x*x). This occurs at x <= 1.

      Warning: This has no checks for overflow. The method is never called when x*x > log(MAX_VALUE/2).

      Parameters:
      x - Value
      Returns:
      exp(x*x)
    • expmxx

      static double expmxx(double x)
      Compute exp(-x*x) with high accuracy. This is performed using information in the round-off from x*x.

      This is accurate at large x to 1 ulp until exp(-x*x) is close to sub-normal. For very small exp(-x*x) the adjustment is sub-normal and bits can be lost in the adjustment for a max observed error of < 2 ulp.

      At small x the accuracy cannot be improved over using exp(-x*x). This occurs at x <= 1.

      Parameters:
      x - Value
      Returns:
      exp(-x*x)
    • expxx

      private static double expxx(double a, double b)
      Compute exp(a+b) with high accuracy assuming a+b = a.

      This is accurate at large positive a to 1 ulp. If a is negative and exp(a) is close to sub-normal a bit of precision may be lost when adjusting result as the adjustment is sub-normal (max observed error < 2 ulp). For the use case of multiplication of a number less than 1 by exp(-x*x), a = -x*x, the result will be sub-normal and the rounding error is lost.

      At small |a| the accuracy cannot be improved over using exp(a) as the round-off is too small to create terms that can adjust the standard result by more than 0.5 ulp. This occurs at |a| <= 1.

      Parameters:
      a - High bits of a split number
      b - Low bits of a split number
      Returns:
      exp(a+b)