ptolemy.math

Class FloatArrayMath

java.lang.Object

ptolemy.math.FloatArrayMath

public class FloatArrayMath
extends java.lang.Object

This class provides a library for mathematical operations on float 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 1.0

Version:

$Id$

Author:

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

Pt.AcceptedRating:

Yellow (ctsay)

Pt.ProposedRating:

Yellow (ctsay)

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	FloatArrayMath()

Method Summary

Modifier and Type	Method and Description
protected static int	_commonLength(float[] array1, float[] 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 float[]	add(float[] array, float z) Return a new array that is the formed by adding z to each element of the input array.
static float[]	add(float[] array1, float[] array2) Return a new array that is the element-by-element sum of the two input arrays.
static float[]	append(float[] array1, float[] array2) Return a new array that is the result of appending array2 to the end of array1.
static float[]	append(float[] array1, int idx1, int length1, float[] array2, int idx2, int length2) Return a new array that is the result of appending length2 elements of array2, starting from the array1[idx2] to length1 elements of array1, starting from array1[idx1].
static float[]	applyBinaryOperation(FloatBinaryOperation op, float[] array, float z) Return a new array that is formed by applying an instance of a FloatBinaryOperation 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 float[]	applyBinaryOperation(FloatBinaryOperation op, float[] array1, float[] array2) Return a new array that is formed by applying an instance of a FloatBinaryOperation 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 float[]	applyBinaryOperation(FloatBinaryOperation op, float z, float[] array) Return a new array that is formed by applying an instance of a FloatBinaryOperation 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 float[]	applyUnaryOperation(FloatUnaryOperation op, float[] array) Return a new array that is formed by applying an instance of a FloatUnaryOperation to each element in the input array (op.operate(array[i])).
static float[]	divide(float[] array, float num) Return a new array that is the element-by-element division of the first array by the given value.
static float[]	divideElements(float[] array1, float[] 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 float	dotProduct(float[] array1, float[] array2) Return the dot product of the two arrays.
static float	l2norm(float[] array) Return the L2-norm of the array, that is, the square root of the sum of the squares of the elements.
static float[]	limit(float[] array, float bottom, float 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 float[]	multiply(float[] array, float 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 float.
static float[]	multiply(float[] array1, float[] array2) Return a new array that is the element-by-element multiplication of the two input arrays.
static float[]	negative(float[] array) Return a new array that is the formed by the additive inverse of each element of the input array (-array[i]).
static float[]	normalize(float[] array) Return a new array that is formed by scaling the array so that it has a L2-norm of 1.
static float[]	padMiddle(float[] array, int newLength) Return a new array of floats that is formed by padding the middle of the array with 0's.
static float[]	resize(float[] array, int newLength) Return a new array of length newLength that is formed by either truncating or padding the input array.
static float[]	resize(float[] array, int newLength, int startIdx) Return a new array of length newLength that is formed by either truncating or padding the input array.
static float[]	scale(float[] array, float scaleFactor) Return a new array of floats produced by scaling the input array elements by scaleFactor.
static float[]	subtract(float[] array1, float[] 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 float	sumOfSquares(float[] array) Return the sum of the squares of all of the elements in the array.
static Complex[]	toComplexArray(float[] array) Return a new array that is formed by converting the floats in the argument array to complex numbers.
static double[]	toDoubleArray(float[] array) Return a new array that is formed by converting the floats in the argument array to doubles.
static int[]	toIntegerArray(float[] array) Return a new array that is formed by converting the floats in the argument array to integers.
static long[]	toLongArray(float[] array) Return a new array that is formed by converting the floats in the argument array to longs.
static java.lang.String	toString(float[] array) Return a new String representing the array, formatted as in Java array initializers.
static java.lang.String	toString(float[] 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(float[] array1, float[] array2, float 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(float[] array1, float[] array2, float[] 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

FloatArrayMath

protected FloatArrayMath()

Method Detail

add

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

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

add

public static final float[] add(float[] array1,
                                float[] 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.

append

public static final float[] append(float[] array1,
                                   float[] 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 float[] append(float[] array1,
                                   int idx1,
                                   int length1,
                                   float[] array2,
                                   int idx2,
                                   int length2)

Return a new array that is the result of appending length2 elements of array2, starting from the array1[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 floats.

idx1 - The starting index for array1.

length1 - The number of elements of array1 to use.

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

idx2 - The starting index for array2.

length2 - The number of elements of array2 to append.

Returns:

A new array of floats.

applyBinaryOperation

public static final float[] applyBinaryOperation(FloatBinaryOperation op,
                                                 float[] array,
                                                 float z)

Return a new array that is formed by applying an instance of a FloatBinaryOperation 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 float[] applyBinaryOperation(FloatBinaryOperation op,
                                                 float z,
                                                 float[] array)

Return a new array that is formed by applying an instance of a FloatBinaryOperation 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 float[] applyBinaryOperation(FloatBinaryOperation op,
                                                 float[] array1,
                                                 float[] array2)

Return a new array that is formed by applying an instance of a FloatBinaryOperation 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 float[] applyUnaryOperation(FloatUnaryOperation op,
                                                float[] array)

Return a new array that is formed by applying an instance of a FloatUnaryOperation 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 float[] divideElements(float[] array1,
                                           float[] 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 floats.

array2 - The second array of floats.

Returns:

A new array of floats.

divide

public static final float[] divide(float[] array,
                                   float 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 float numbers.

num - The float scalar.

Returns:

A new array of float numbers.

dotProduct

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

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

l2norm

public static final float l2norm(float[] 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 float[] limit(float[] array,
                                  float bottom,
                                  float 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 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 Float.NEGATIVE_INFINITY or Float.POSITIVE_INFINITY. If the length of the array is 0, return a new array of length 0.

Parameters:

array - An array of floats.

bottom - The bottom limit.

top - The top limit.

Returns:

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

multiply

public static final float[] multiply(float[] array1,
                                     float[] 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 float[] multiply(float[] array,
                                     float 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 float. If the sizes of the array is 0, return a new array of size 0.

Parameters:

array - An array of floats.

factor - A float.

Returns:

A new array of floats.

negative

public static final float[] negative(float[] 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 float[] normalize(float[] 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 float[] padMiddle(float[] array,
                                      int newLength)

Return a new array of floats 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 floats.

newLength - The desired length of the returned array.

Returns:

A new array of floats.

resize

public static final float[] resize(float[] 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 floats.

newLength - The desired length of the output array.

Returns:

A new array of floats of length newLength.

resize

public static final float[] resize(float[] 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 floats.

newLength - The desired length of the output array.

startIdx - The starting index for the input array.

Returns:

A new array of floats of length newLength.

scale

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

Return a new array of floats 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 float[] subtract(float[] array1,
                                     float[] 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.

sumOfSquares

public static final float sumOfSquares(float[] 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.0f if the length of the array is 0.

toComplexArray

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

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

Parameters:

array - An array of floats.

Returns:

A new array of complex numbers.

toDoubleArray

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

Return a new array that is formed by converting the floats 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 float.

Returns:

A new array of doubles.

toIntegerArray

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

Return a new array that is formed by converting the floats 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 float.

Returns:

A new array of integers.

toLongArray

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

Return a new array that is formed by converting the floats 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 float.

Returns:

A new array of longs.

toString

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

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

toString

public static final java.lang.String toString(float[] 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(float[] array1,
                                   float[] array2,
                                   float 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(float[] array1,
                                   float[] array2,
                                   float[] 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(float[] array1,
                                         float[] 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 floats.

array2 - The second array of floats.

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

Returns:

The common length of both arrays.