org.apache.commons.math3.dfp

## Class DfpMath

- java.lang.Object
- - org.apache.commons.math3.dfp.DfpMath

-     public class DfpMath
      extends Object

  Mathematical routines for use with `Dfp`. The constants are defined in `DfpField`
  Since:
    2.2
  Version:
    $Id: DfpMath.java 1416643 2012-12-03 19:37:14Z tn $

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private static String` | `POW_TRAP` Name for traps triggered by pow.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `private` | `DfpMath()` Private Constructor.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static Dfp` | `acos(Dfp a)` computes the arc-cosine of the argument.
    `static Dfp` | `asin(Dfp a)` computes the arc-sine of the argument.
    `static Dfp` | `atan(Dfp a)` computes the arc tangent of the argument Uses the typical taylor series but may reduce arguments using the following identity tan(x+y) = (tan(x) + tan(y)) / (1 - tan(x)*tan(y)) since tan(PI/8) = sqrt(2)-1, atan(x) = atan( (x - sqrt(2) + 1) / (1+x*sqrt(2) - x) + PI/8.0
    `protected static Dfp` | `atanInternal(Dfp a)` computes the arc-tangent of the argument.
    `static Dfp` | `cos(Dfp a)` computes the cosine of the argument.
    `protected static Dfp` | `cosInternal(Dfp[] a)` Computes cos(a) Used when 0 < a < pi/4.
    `static Dfp` | `exp(Dfp a)` Computes e to the given power.
    `protected static Dfp` | `expInternal(Dfp a)` Computes e to the given power.
    `static Dfp` | `log(Dfp a)` Returns the natural logarithm of a.
    `protected static Dfp[]` | `logInternal(Dfp[] a)` Computes the natural log of a number between 0 and 2.
    `static Dfp` | `pow(Dfp x, Dfp y)` Computes x to the y power.
    `static Dfp` | `pow(Dfp base, int a)` Raises base to the power a by successive squaring.
    `static Dfp` | `sin(Dfp a)` computes the sine of the argument.
    `protected static Dfp` | `sinInternal(Dfp[] a)` Computes sin(a) Used when 0 < a < pi/4.
    `protected static Dfp[]` | `split(Dfp a)` Splits a `Dfp` into 2 `Dfp`'s such that their sum is equal to the input `Dfp`.
    `protected static Dfp[]` | `split(DfpField field, String a)` Breaks a string representation up into two dfp's.
    `protected static Dfp[]` | `splitDiv(Dfp[] a, Dfp[] b)` Divide two numbers that are split in to two pieces that are meant to be added together.
    `protected static Dfp[]` | `splitMult(Dfp[] a, Dfp[] b)` Multiply two numbers that are split in to two pieces that are meant to be added together.
    `protected static Dfp` | `splitPow(Dfp[] base, int a)` Raise a split base to the a power.
    `static Dfp` | `tan(Dfp a)` computes the tangent of the argument.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### POW_TRAP

          private static final String POW_TRAP

      Name for traps triggered by pow.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### DfpMath

          private DfpMath()

      Private Constructor.

  - ### Method Detail

    - #### split

          protected static Dfp[] split(DfpField field,
                    String a)

      Breaks a string representation up into two dfp's.

      The two dfp are such that the sum of them is equivalent to the input string, but has higher precision than using a single dfp. This is useful for improving accuracy of exponentiation and critical multiplies.

      Parameters:
        `field` - field to which the Dfp must belong
        `a` - string representation to split
      Returns:
        an array of two `Dfp` which sum is a

    - #### split

          protected static Dfp[] split(Dfp a)

      Splits a `Dfp` into 2 `Dfp`'s such that their sum is equal to the input `Dfp`.
      Parameters:
        `a` - number to split
      Returns:
        two elements array containing the split number

    - #### splitMult

          protected static Dfp[] splitMult(Dfp[] a,
                        Dfp[] b)

      Multiply two numbers that are split in to two pieces that are meant to be added together. Use binomial multiplication so ab = a0 b0 + a0 b1 + a1 b0 + a1 b1 Store the first term in result0, the rest in result1
      Parameters:
        `a` - first factor of the multiplication, in split form
        `b` - second factor of the multiplication, in split form
      Returns:
        a × b, in split form

    - #### splitDiv

          protected static Dfp[] splitDiv(Dfp[] a,
                       Dfp[] b)

      Divide two numbers that are split in to two pieces that are meant to be added together. Inverse of split multiply above: (a+b) / (c+d) = (a/c) + ( (bc-ad)/(c**2+cd) )
      Parameters:
        `a` - dividend, in split form
        `b` - divisor, in split form
      Returns:
        a / b, in split form

    - #### splitPow

          protected static Dfp splitPow(Dfp[] base,
                     int a)

      Raise a split base to the a power.
      Parameters:
        `base` - number to raise
        `a` - power
      Returns:
        basea

    - #### pow

          public static Dfp pow(Dfp base,
                int a)

      Raises base to the power a by successive squaring.
      Parameters:
        `base` - number to raise
        `a` - power
      Returns:
        basea

    - #### exp

          public static Dfp exp(Dfp a)

      Computes e to the given power. a is broken into two parts, such that a = n+m where n is an integer. We use pow() to compute en and a Taylor series to compute em. We return e*n × em
      Parameters:
        `a` - power at which e should be raised
      Returns:
        ea

    - #### expInternal

          protected static Dfp expInternal(Dfp a)

      Computes e to the given power. Where -1 < a < 1. Use the classic Taylor series. 1 + x**2/2! + x**3/3! + x**4/4! ...
      Parameters:
        `a` - power at which e should be raised
      Returns:
        ea

    - #### log

          public static Dfp log(Dfp a)

      Returns the natural logarithm of a. a is first split into three parts such that a = (10000^h)(2^j)k. ln(a) is computed by ln(a) = ln(5)*h + ln(2)*(h+j) + ln(k) k is in the range 2/3 < k <4/3 and is passed on to a series expansion.
      Parameters:
        `a` - number from which logarithm is requested
      Returns:
        log(a)

    - #### logInternal

          protected static Dfp[] logInternal(Dfp[] a)

      Computes the natural log of a number between 0 and 2. Let f(x) = ln(x), We know that f'(x) = 1/x, thus from Taylor's theorum we have: ----- n+1 n f(x) = \ (-1) (x - 1) / ---------------- for 1 <= n <= infinity ----- n or 2 3 4 (x-1) (x-1) (x-1) ln(x) = (x-1) - ----- + ------ - ------ + ... 2 3 4 alternatively, 2 3 4 x x x ln(x+1) = x - - + - - - + ... 2 3 4 This series can be used to compute ln(x), but it converges too slowly. If we substitute -x for x above, we get 2 3 4 x x x ln(1-x) = -x - - - - - - + ... 2 3 4 Note that all terms are now negative. Because the even powered ones absorbed the sign. Now, subtract the series above from the previous one to get ln(x+1) - ln(1-x). Note the even terms cancel out leaving only the odd ones 3 5 7 2x 2x 2x ln(x+1) - ln(x-1) = 2x + --- + --- + ---- + ... 3 5 7 By the property of logarithms that ln(a) - ln(b) = ln (a/b) we have: 3 5 7 x+1 / x x x \ ln ----- = 2 * | x + ---- + ---- + ---- + ... | x-1 \ 3 5 7 / But now we want to find ln(a), so we need to find the value of x such that a = (x+1)/(x-1). This is easily solved to find that x = (a-1)/(a+1).
      Parameters:
        `a` - number from which logarithm is requested, in split form
      Returns:
        log(a)

    - #### pow

          public static Dfp pow(Dfp x,
                Dfp y)

      Computes x to the y power.

      Uses the following method:

      1. Set u = rint(y), v = y-u
      2. Compute a = v * ln(x)
      3. Compute b = rint( a/ln(2) )
      4. Compute c = a - b*ln(2)
      5. xy = xu * 2b * ec
      if |y| > 1e8, then we compute by exp(y*ln(x))

      Special Cases

      - if y is 0.0 or -0.0 then result is 1.0
      - if y is 1.0 then result is x
      - if y is NaN then result is NaN
      - if x is NaN and y is not zero then result is NaN
      - if |x| > 1.0 and y is +Infinity then result is +Infinity
      - if |x| < 1.0 and y is -Infinity then result is +Infinity
      - if |x| > 1.0 and y is -Infinity then result is +0
      - if |x| < 1.0 and y is +Infinity then result is +0
      - if |x| = 1.0 and y is +/-Infinity then result is NaN
      - if x = +0 and y > 0 then result is +0
      - if x = +Inf and y < 0 then result is +0
      - if x = +0 and y < 0 then result is +Inf
      - if x = +Inf and y > 0 then result is +Inf
      - if x = -0 and y > 0, finite, not odd integer then result is +0
      - if x = -0 and y < 0, finite, and odd integer then result is -Inf
      - if x = -Inf and y > 0, finite, and odd integer then result is -Inf
      - if x = -0 and y < 0, not finite odd integer then result is +Inf
      - if x = -Inf and y > 0, not finite odd integer then result is +Inf
      - if x < 0 and y > 0, finite, and odd integer then result is -(|x|y)
      - if x < 0 and y > 0, finite, and not integer then result is NaN
      Parameters:
        `x` - base to be raised
        `y` - power to which base should be raised
      Returns:
        xy

    - #### sinInternal

          protected static Dfp sinInternal(Dfp[] a)

      Computes sin(a) Used when 0 < a < pi/4. Uses the classic Taylor series. x - x**3/3! + x**5/5! ...
      Parameters:
        `a` - number from which sine is desired, in split form
      Returns:
        sin(a)

    - #### cosInternal

          protected static Dfp cosInternal(Dfp[] a)

      Computes cos(a) Used when 0 < a < pi/4. Uses the classic Taylor series for cosine. 1 - x**2/2! + x**4/4! ...
      Parameters:
        `a` - number from which cosine is desired, in split form
      Returns:
        cos(a)

    - #### sin

          public static Dfp sin(Dfp a)

      computes the sine of the argument.
      Parameters:
        `a` - number from which sine is desired
      Returns:
        sin(a)

    - #### cos

          public static Dfp cos(Dfp a)

      computes the cosine of the argument.
      Parameters:
        `a` - number from which cosine is desired
      Returns:
        cos(a)

    - #### tan

          public static Dfp tan(Dfp a)

      computes the tangent of the argument.
      Parameters:
        `a` - number from which tangent is desired
      Returns:
        tan(a)

    - #### atanInternal

          protected static Dfp atanInternal(Dfp a)

      computes the arc-tangent of the argument.
      Parameters:
        `a` - number from which arc-tangent is desired
      Returns:
        atan(a)

    - #### atan

          public static Dfp atan(Dfp a)

      computes the arc tangent of the argument Uses the typical taylor series but may reduce arguments using the following identity tan(x+y) = (tan(x) + tan(y)) / (1 - tan(x)*tan(y)) since tan(PI/8) = sqrt(2)-1, atan(x) = atan( (x - sqrt(2) + 1) / (1+x*sqrt(2) - x) + PI/8.0
      Parameters:
        `a` - number from which arc-tangent is desired
      Returns:
        atan(a)

    - #### asin

          public static Dfp asin(Dfp a)

      computes the arc-sine of the argument.
      Parameters:
        `a` - number from which arc-sine is desired
      Returns:
        asin(a)

    - #### acos

          public static Dfp acos(Dfp a)

      computes the arc-cosine of the argument.
      Parameters:
        `a` - number from which arc-cosine is desired
      Returns:
        acos(a)

Copyright (c) 2003-2013 Apache Software Foundation