ptolemy.math
Class DoubleArrayMath

java.lang.Object
  ptolemy.math.DoubleArrayMath

Direct Known Subclasses:

DoubleArrayStat

public class DoubleArrayMath
extends java.lang.Object

This class provides a library for mathematical operations on double arrays. unless explicitly noted otherwise, all array arguments are assumed to be non-null. If a null array is passed to a method, a NullPointerException will be thrown in the method or called methods.

Since:

Ptolemy II 0.3

Version:

$Id: DoubleArrayMath.java 57040 2010-01-27 20:52:32Z cxh $

Author:

Albert Chen, William Wu, Edward A. Lee, Jeff Tsay

Accepted Rating:

Yellow (ctsay)

Proposed Rating:

Yellow (ctsay)

Constructor Summary

protected

DoubleArrayMath()

Method Summary

protected static int	_commonLength(double[] array1, double[] array2, java.lang.String methodName) Throw an exception if the two arrays are not of the same length, or if either array is null.
static double[]	add(double[] array, double z) Return a new array that is the formed by adding z to each element of the input array.
static double[]	add(double[] array1, double[] array2) Return a new array that is the element-by-element sum of the two input arrays.
static double[]	allocCopy(double[] array) Return a new array that is a copy of the array argument.
static double[]	append(double[] array1, double[] array2) Return a new array that is the result of appending array2 to the end of array1.
static double[]	append(double[] array1, int idx1, int length1, double[] array2, int idx2, int length2) Return a new array that is the result of appending length2 elements of array2, starting from the array2[idx2] to length1 elements of array1, starting from array1[idx1].
static double[]	applyBinaryOperation(DoubleBinaryOperation op, double[] array, double z) Return a new array that is formed by applying an instance of a DoubleBinaryOperation to each element in the input array and z, using the array elements as the left operands and z as the right operand in all cases.
static double[]	applyBinaryOperation(DoubleBinaryOperation op, double[] array1, double[] array2) Return a new array that is formed by applying an instance of a DoubleBinaryOperation to the two arrays, element by element, using the elements of the first array as the left operands and the elements of the second array as the right operands.
static double[]	applyBinaryOperation(DoubleBinaryOperation op, double z, double[] array) Return a new array that is formed by applying an instance of a DoubleBinaryOperation to each element in the input array, using z as the left operand in all cases and the array elements as the right operands (op.operate(z, array[i])).
static double[]	applyUnaryOperation(DoubleUnaryOperation op, double[] array) Return a new array that is formed by applying an instance of a DoubleUnaryOperation to each element in the input array (op.operate(array[i])).
static double[]	divide(double[] array, double num) Return a new array that is the element-by-element division of the first array by the given value.
static double[]	divideElements(double[] array1, double[] array2) Return a new array that is the element-by-element division of the first array by the second array (array1[i] / array2[i]).
static double	dotProduct(double[] array1, double[] array2) Return the dot product of the two arrays.
static double	l2norm(double[] array) Return the L2-norm of the array, that is, the square root of the sum of the squares of the elements.
static double[]	limit(double[] array, double bottom, double top) Return a new array that is a copy of the argument except that the elements are limited to lie within the specified range.
static double[]	modulo(double[] array, double z) Return a new array that is the formed by the modulo of each element of the input array and z (array[i] % z).
static double[]	multiply(double[] array, double factor) Return a new array that is constructed from the argument by multiplying each element in the array by the second argument, which is a double.
static double[]	multiply(double[] array1, double[] array2) Return a new array that is the element-by-element multiplication of the two input arrays.
static double[]	negative(double[] array) Return a new array that is the formed by the additive inverse of each element of the input array (-array[i]).
static double[]	normalize(double[] array) Return a new array that is formed by scaling the array so that it has a L2-norm of 1.
static double[]	padMiddle(double[] array, int newLength) Return a new array of doubles that is formed by padding the middle of the array with 0's.
static double[]	resize(double[] array, int newLength) Return a new array of length newLength that is formed by either truncating or padding the input array.
static double[]	resize(double[] array, int newLength, int startIdx) Return a new array of length newLength that is formed by either truncating or padding the input array.
static double[]	scale(double[] array, double scaleFactor) Return a new array of doubles produced by scaling the input array elements by scaleFactor.
static double[]	subtract(double[] array1, double[] array2) Return a new array that is the element-by-element difference of the two input arrays, i.e. the first array minus the second array (array1[i] - array2[i]).
static double	sum(double[] array) Return the sum of the elements in the array.
static double	sumOfSquares(double[] array) Return the sum of the squares of all of the elements in the array.
static Complex[]	toComplexArray(double[] array) Return a new array that is formed by converting the doubles in the argument array to complex numbers.
static float[]	toFloatArray(double[] array) Return a new array that is formed by converting the doubles in the argument array to doubles.
static int[]	toIntegerArray(double[] array) Return a new array that is formed by converting the doubles in the argument array to integers.
static long[]	toLongArray(double[] array) Return a new array that is formed by converting the doubles in the argument array to longs.
static java.lang.String	toString(double[] array) Return a new String representing the array, formatted as in Java array initializers.
static java.lang.String	toString(double[] array, java.lang.String elementDelimiter, java.lang.String vectorBegin, java.lang.String vectorEnd) Return a new String representing the array, formatted as specified by the ArrayStringFormat argument.
static boolean	within(double[] array1, double[] array2, double maxError) Return true if all the distances between corresponding elements array1 and array2 are all less than or equal to the corresponding elements in maxError.
static boolean	within(double[] array1, double[] array2, double[] maxError) Return true if all the distances between corresponding elements array1 and array2 are all less than or equal to the corresponding elements in maxError.

Methods inherited from class java.lang.Object

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

Constructor Detail

DoubleArrayMath

protected DoubleArrayMath()

Method Detail

add

public static final double[] add(double[] array,
                                 double z)

Return a new array that is the formed by adding z to each element of the input array.

add

public static final double[] add(double[] array1,
                                 double[] array2)

Return a new array that is the element-by-element sum of the two input arrays. If the lengths of both arrays are 0, return a new array of length 0. If the two arrays do not have the same length, throw an IllegalArgumentException.

allocCopy

public static final double[] allocCopy(double[] array)

Return a new array that is a copy of the array argument.

Parameters:

array - An array of ints.

Returns:

A new array of ints.

append

public static final double[] append(double[] array1,
                                    double[] array2)

Return a new array that is the result of appending array2 to the end of array1. This method simply calls append(array1, 0, array1.length, array2, 0, array2.length)

append

public static final double[] append(double[] array1,
                                    int idx1,
                                    int length1,
                                    double[] array2,
                                    int idx2,
                                    int length2)

Return a new array that is the result of appending length2 elements of array2, starting from the array2[idx2] to length1 elements of array1, starting from array1[idx1]. Appending empty arrays is supported. In that case, the corresponding idx may be any number. Allow System.arraycopy() to throw array access exceptions if idx .. idx + length - 1 are not all valid array indices, for both of the arrays.

Parameters:

array1 - The first array of doubles.

idx1 - The starting index for array1.

length1 - The number of elements of array1 to use.

array2 - The second array of doubles, which is appended.

idx2 - The starting index for array2.

length2 - The number of elements of array2 to append.

Returns:

A new array of doubles.

applyBinaryOperation

public static final double[] applyBinaryOperation(DoubleBinaryOperation op,
                                                  double[] array,
                                                  double z)

Return a new array that is formed by applying an instance of a DoubleBinaryOperation to each element in the input array and z, using the array elements as the left operands and z as the right operand in all cases. (op.operate(array[i], z)). If the length of the array is 0, return a new array of length 0.

applyBinaryOperation

public static final double[] applyBinaryOperation(DoubleBinaryOperation op,
                                                  double z,
                                                  double[] array)

Return a new array that is formed by applying an instance of a DoubleBinaryOperation to each element in the input array, using z as the left operand in all cases and the array elements as the right operands (op.operate(z, array[i])). If the length of the array is 0, return a new array of length 0.

applyBinaryOperation

public static final double[] applyBinaryOperation(DoubleBinaryOperation op,
                                                  double[] array1,
                                                  double[] array2)

Return a new array that is formed by applying an instance of a DoubleBinaryOperation to the two arrays, element by element, using the elements of the first array as the left operands and the elements of the second array as the right operands. (op.operate(array[i], array2[i])). If the lengths of both arrays are 0, return a new array of length 0. If the two arrays do not have the same length, throw an IllegalArgumentException.

applyUnaryOperation

public static final double[] applyUnaryOperation(DoubleUnaryOperation op,
                                                 double[] array)

Return a new array that is formed by applying an instance of a DoubleUnaryOperation to each element in the input array (op.operate(array[i])). If the length of the array is 0, return a new array of length 0.

divideElements

public static final double[] divideElements(double[] array1,
                                            double[] array2)

Return a new array that is the element-by-element division of the first array by the second array (array1[i] / array2[i]). If the lengths of both arrays are 0, return a new array of length 0. If the two arrays do not have the same length, throw an IllegalArgumentException.

Parameters:

array1 - The first array of doubles.

array2 - The second array of doubles.

Returns:

A new array of doubles.

divide

public static final double[] divide(double[] array,
                                    double num)

Return a new array that is the element-by-element division of the first array by the given value.

Parameters:

array - The array of double numbers.

num - The double scalar.

Returns:

A new array of double numbers.

dotProduct

public static final double dotProduct(double[] array1,
                                      double[] array2)

Return the dot product of the two arrays. If the lengths of the array are both 0, return 0.0. If the two arrays do not have the same length, throw an IllegalArgumentException.

l2norm

public static final double l2norm(double[] array)

Return the L2-norm of the array, that is, the square root of the sum of the squares of the elements.

limit

public static final double[] limit(double[] array,
                                   double bottom,
                                   double top)

Return a new array that is a copy of the argument except that the elements are limited to lie within the specified range. If any value is infinite, then it is replaced by either the top or the bottom, depending on its sign. If any element of the array is NaN, then the corresponding element in the new array will also be NaN. To leave either the bottom or the top unconstrained, specify Double.NEGATIVE_INFINITY or Double.POSITIVE_INFINITY.

If the length of the array is 0, return a new array of length 0.

Parameters:

array - An array of doubles.

bottom - The bottom limit.

top - The top limit.

Returns:

A new array with values in the range [bottom, top].

modulo

public static final double[] modulo(double[] array,
                                    double z)

Return a new array that is the formed by the modulo of each element of the input array and z (array[i] % z).

multiply

public static final double[] multiply(double[] array1,
                                      double[] array2)

Return a new array that is the element-by-element multiplication of the two input arrays. If the lengths of both arrays are 0, return a new array of length 0. If the two arrays do not have the same length, throw an IllegalArgumentException.

multiply

public static final double[] multiply(double[] array,
                                      double factor)

Return a new array that is constructed from the argument by multiplying each element in the array by the second argument, which is a double. If the sizes of the array is 0, return a new array of size 0.

Parameters:

array - An array of doubles.

factor - A double.

Returns:

A new array of doubles.

negative

public static final double[] negative(double[] array)

Return a new array that is the formed by the additive inverse of each element of the input array (-array[i]).

normalize

public static final double[] normalize(double[] array)

Return a new array that is formed by scaling the array so that it has a L2-norm of 1.

padMiddle

public static final double[] padMiddle(double[] array,
                                       int newLength)

Return a new array of doubles that is formed by padding the middle of the array with 0's. If either the length of the input array is odd, the sample with index ceil(L/2) will be repeated in the output array, where L is the length of the input array. If the length of the input and output arrays are equal, return a copy of the input array. This method is useful for preparing data for an IFFT.

Parameters:

array - An array of doubles.

newLength - The desired length of the returned array.

Returns:

A new array of doubles.

resize

public static final double[] resize(double[] array,
                                    int newLength)

Return a new array of length newLength that is formed by either truncating or padding the input array. This method simply calls : resize(array, newLength, 0)

Parameters:

array - An array of doubles.

newLength - The desired length of the output array.

Returns:

A new array of doubles of length newLength.

resize

public static final double[] resize(double[] array,
                                    int newLength,
                                    int startIdx)

Return a new array of length newLength that is formed by either truncating or padding the input array. Elements from the input array are copied to the output array, starting from array[startIdx] until one of the following conditions is met :

1. The input array has no more elements to copy.
2. The output array has been completely filled.

startIdx must index a valid entry in array unless the input array is of zero length or the output array is of zero length. If case 1) is met, the remainder of the output array is filled with zero's, implicitly by Java (padding).

Parameters:

array - An array of doubles.

newLength - The desired length of the output array.

startIdx - The starting index for the input array.

Returns:

A new array of doubles of length newLength.

scale

public static final double[] scale(double[] array,
                                   double scaleFactor)

Return a new array of doubles produced by scaling the input array elements by scaleFactor. If the length of the array is 0, return a new array of length 0.

subtract

public static final double[] subtract(double[] array1,
                                      double[] array2)

Return a new array that is the element-by-element difference of the two input arrays, i.e. the first array minus the second array (array1[i] - array2[i]). If the lengths of both arrays are 0, return a new array of length 0.

sum

public static final double sum(double[] array)

Return the sum of the elements in the array. Return 0.0 if the length of the array is 0.

sumOfSquares

public static final double sumOfSquares(double[] array)

Return the sum of the squares of all of the elements in the array. This is equivalent to the square of the L2-norm of the array. Return 0.0 if the length of the array is 0.

toComplexArray

public static final Complex[] toComplexArray(double[] array)

Return a new array that is formed by converting the doubles in the argument array to complex numbers. Each complex number has real part equal to the value in the argument array and a zero imaginary part.

Parameters:

array - An array of double.

Returns:

A new array of complex numbers.

toFloatArray

public static final float[] toFloatArray(double[] array)

Return a new array that is formed by converting the doubles in the argument array to doubles. If the length of the argument array is 0, return a new array of length 0.

Parameters:

array - An array of double.

Returns:

A new array of doubles.

toIntegerArray

public static final int[] toIntegerArray(double[] array)

Return a new array that is formed by converting the doubles in the argument array to integers. If the length of the argument array is 0, return a new array of length 0.

Parameters:

array - An array of double.

Returns:

A new array of integers.

toLongArray

public static final long[] toLongArray(double[] array)

Return a new array that is formed by converting the doubles in the argument array to longs. If the length of the argument array is 0, return a new array of length 0.

Parameters:

array - An array of double.

Returns:

A new array of longs.

toString

public static final java.lang.String toString(double[] array)

Return a new String representing the array, formatted as in Java array initializers.

toString

public static final java.lang.String toString(double[] array,
                                              java.lang.String elementDelimiter,
                                              java.lang.String vectorBegin,
                                              java.lang.String vectorEnd)

Return a new String representing the array, formatted as specified by the ArrayStringFormat argument. To get a String in the Ptolemy expression language format, call this method with ArrayStringFormat.exprASFormat as the format argument.

within

public static final boolean within(double[] array1,
                                   double[] array2,
                                   double maxError)

Return true if all the distances between corresponding elements array1 and array2 are all less than or equal to the corresponding elements in maxError. If both arrays are empty, return true. If maxError is negative, return false.

Parameters:

array1 - The first array.

array2 - The second array.

maxError - The threshold for the magnitude of the difference.

Returns:

True if all the distances between corresponding elements array1 and array2 are all less than or equal to the corresponding elements in maxError.

Throws:

java.lang.IllegalArgumentException - If the arrays are not of the same length.

within

public static final boolean within(double[] array1,
                                   double[] array2,
                                   double[] maxError)

Return true if all the distances between corresponding elements array1 and array2 are all less than or equal to the corresponding elements in maxError. If both arrays are empty, return true. If any element of maxError is negative, return false.

Parameters:

array1 - The first array.

array2 - The second array.

maxError - The array of thresholds for the magnitudes of the difference.

Returns:

True if all the distances between corresponding elements array1 and array2 are all less than or equal to the corresponding elements in maxError.

Throws:

java.lang.IllegalArgumentException - If the arrays are not of the same length.

_commonLength

protected static final int _commonLength(double[] array1,
                                         double[] array2,
                                         java.lang.String methodName)

Throw an exception if the two arrays are not of the same length, or if either array is null. An exception is NOT thrown if both arrays are of length 0. If no exception is thrown, return the common length of the arrays.

Parameters:

array1 - The first array of doubles.

array2 - The second array of doubles.

methodName - A String representing the method name of the caller, without parentheses.

Returns:

The common length of both arrays.