Copyright: Thomas Rode / DL1DUZ
Release: 0.2
09/05/2012

Class BigMath

public final class BigMath

Provides arbitrary precision calculation of some mathematical functions and constants as well as some format
transformation tools based on the "BigInteger" number format. For implementation "java.math" must be imported.
 
Constructor:

BigMath()

Methods:

 public static BigInteger getPi(int digits)
            Returns a BigInteger whose value is Pi with a precision of "digits" after the decimal separator.
            The algorithm uses a BBP formula.
            Example: getPi(4) returns 31415
            Throws: "IllegalArgumentException" for digits<0

 public static BigInteger getE(int digits)
            Returns a BigInteger whose value is e (Eulers number) with a precision of "digits" after the decimal separator.
            The algorithm uses a Taylor formula.
            Example: getE(4) returns 27182
            Throws: "IllegalArgumentException" for digits<0

 public static BigInteger getFactorial(int x)
            Returns a BigInteger whose value is x! The data of x and x! from the last call will be stored to
            achive fast calculation in case of x being closer to x_old than to Zero. For large x, the algorithm
            will automatically switch to the binary-split formula to speed up calculation even further.
            Example: getFactorial(4) returns 24
            Throws: "IllegalArgumentException" for digits<0

 public static BigInteger getRoot(BigInteger x, int digits, int root)
            Returns a BigInteger whose value is root(x). The algorithm uses a successive approximation approach.
            The precision is digits after the decimal separator.
            Example: getRoot(20000, 4, 2) returns 14142
            Throws: "IllegalArgumentException" for digits<0, x<0, root<1

 public static BigInteger getLd(BigInteger x, int InDigits, int OutDigits)
            Returns a BigInteger whose value is ld(x). The algorithm calculates ld(x) recursively taking advantage of
            the relation ld(x^2) = 2*ld(x) to calculate the binary representation of the floor-part separately.
            "OutDigits" is the requested number of digits after the decimal separator at the return value ld(x).
            "InDigits" specifies the number of digits after the decimal separator for x.
            Example: getLd(1234, 4, 6) returns -3018585
            Throws: "IllegalArgumentException" for InDigits<0, OutDigits<0, x<=0

 public static BigInteger getSinCos(BigInteger x, int digits, Boolean CalculateSine)
            Returns a BigInteger whose value is sin(x) if CalculateSine==True or cos(x) if CalculateSine==False. The
            algorithm is based on a Taylor formula. The precision is digits after the decimal separator. x must be
            given as Radian.
            Example: getSinCos(15708, 4, true) returns 10000
            Throws: "IllegalArgumentException" for digits<0

 public static BigInteger getAsinAcos(BigInteger x, int digits, Boolean CalculateASine)
            Returns a BigInteger whose value is asin(x) if CalculateASine==True or acos(x) if CalculateASine==False.
            The algorithm uses a successive approximation approach by calculating the Sine/Cosine. The precision is
            digits after the decimal separator.
            Example: getASinACos(7071, 4, true) returns 7853
            Throws: "IllegalArgumentException" for digits<0, -1>x>1.

 public static BigInteger getTan(BigInteger x, int digits)
            Returns a BigInteger whose value is tan(x). If x is a pole, tan(x) returns "null". The algorithm uses the
            "getSinCos()" function.
            The precision is digits after the decimal separator. x must be given as Radian.
            Example: getTan(7854, 4) returns 10000
            Throws: "IllegalArgumentException" for digits<0

 public static BigInteger getAtan(BigInteger x, int digits)
            Returns a BigInteger whose value is atan(x).
            The algorithm uses "getAsinAcos" for calculation. The precision is digits after the decimal separator.
            Example: getASinACos(5000, 2) returns 155
            Throws: "IllegalArgumentException" for digits<0.

 public static BigInteger reverseBits(BigInteger x, int power)
            Permutes x ending at Bit (power-1) and returns the result as an BigInteger. The algorithm is known as
            "Bit Reversal". The maximum value of x is (2^power)-1, the minimum is 0.
            Example: reverseBits(3, 3) returns 6, since the binary representation 011 is converted to 110.
            Throws: "IllegalArgumentException" for power<1, x<0 x>(2^power)-1

 public static BigInteger[] ByteToBigInteger(byte[] input, int SizeSet, Boolean BigEndian)
             Returns an array of BigInteger using the Byte-array "input" as an basis. The parameter "SizeSet" specifies
             the number of Bytes to be converted into a single BigInteger. If "BigEndian" is True, the data in the
             Byte-array is assumed to be BigEndian (most significant Byte at lowest index position).
             Throws: "IllegalArgumentException" if the length of the Byte-array is not a multiple of "SizeSet" or if
             SizeSet<1.

 public static byte[] BigIntegerToByte(BigInteger[] input, int SizeSet, Boolean BigEndian)
             Returns a Byte-array using the array "input" as an basis. The parameter "SizeSet" specifies
             the number of Bytes reserved for each element of "input" (each BigInteger). If "BigEndian" is True, the data
             in the Byte-array will be BigEndian (most significant Byte at lowest index position).
             Throws: "ArrayIndexOutOfBoundsException" if the size of one or more elements of "input" exceed the size 
             specified by "SizeSet".
             Throws: "IllegalArgumentException" if SizeSet<1.

 public static FFTdata doFFT(FFTdata data)
             Calculates a Fast Fourier Transform. Input and return value are objects of the class "FFTdata". For details
             please refer to "FFTdata_description.txt" in this folder. The resulting values (frequency domain data) is
             divided by the size of the FFT (2^power). To reduce the computational effort, "doFFT" checks if the structure
             of "data" (length of the arrays and max number of digits) has changed from the previous call. If not, the Sine
             table will not be recalculated.

 public static FFTdata doIFFT(FFTdata data)
             Calculates a Inverse Fast Fourier Transform. Input and return value are objects of the class "FFTdata". For
             details please refer to "FFTdata_description.txt" in this folder. The resulting values (time domain data) will
             not be normalized. Therefore the output from "doFFT" can directly be used as intput for "doIFFT". To reduce
             the computational effort, "doIFFT" checks if the structure of "data" (length of the arrays and max number of
             digits) has changed from the previous call. If not, the Sine table will not be recalculated. "doFFT" and
             "doIFFT" share the same Sine table. Hence, if repeatedly calculating FFTs and and IFFTs of different sizes,
             two seperate instances should be used to reduce computational effort.