org.apache.commons.math3.util
Class MathArrays

java.lang.Object
  org.apache.commons.math3.util.MathArrays

public class MathArrays
extends Object

Arrays utilities.

Since:

3.0

Version:

$Id: MathArrays.java 14143 2015-10-07 14:23:17Z galpin $

Nested Class Summary

static interface	MathArrays.Function Real-valued function that operate on an array or a part of it.
static class	MathArrays.OrderDirection Specification of ordering direction.

Method Summary

static <T> T[]	buildArray(Field<T> field, int length) Build an array of elements.
static <T> T[][]	buildArray(Field<T> field, int rows, int columns) Build a double dimension array of elements.
static void	checkNonNegative(long[] in) Check that all entries of the input array are >= 0.
static void	checkNonNegative(long[][] in) Check all entries of the input array are >= 0.
static void	checkOrder(double[] val) Check that the given array is sorted in strictly increasing order.
static void	checkOrder(double[] val, MathArrays.OrderDirection dir, boolean strict) Check that the given array is sorted.
static boolean	checkOrder(double[] val, MathArrays.OrderDirection dir, boolean strict, boolean abort) Check that the given array is sorted.
static void	checkPositive(double[] in) Check that all entries of the input array are strictly positive.
static void	checkRectangular(long[][] in) Throws DimensionMismatchException if the input array is not rectangular.
static double[]	copyOf(double[] source) Creates a copy of the source array.
static double[]	copyOf(double[] source, int len) Creates a copy of the source array.
static int[]	copyOf(int[] source) Creates a copy of the source array.
static int[]	copyOf(int[] source, int len) Creates a copy of the source array.
static double	distance(double[] p1, double[] p2) Calculates the L2 (Euclidean) distance between two points.
static double	distance(int[] p1, int[] p2) Calculates the L2 (Euclidean) distance between two points.
static double	distance1(double[] p1, double[] p2) Calculates the L1 (sum of abs) distance between two points.
static int	distance1(int[] p1, int[] p2) Calculates the L1 (sum of abs) distance between two points.
static double	distanceInf(double[] p1, double[] p2) Calculates the L∞ (max of abs) distance between two points.
static int	distanceInf(int[] p1, int[] p2) Calculates the L∞ (max of abs) distance between two points.
static double[]	ebeAdd(double[] a, double[] b) Creates an array whose contents will be the element-by-element addition of the arguments.
static double[]	ebeDivide(double[] a, double[] b) Creates an array whose contents will be the element-by-element division of the first argument by the second.
static double[]	ebeMultiply(double[] a, double[] b) Creates an array whose contents will be the element-by-element multiplication of the arguments.
static double[]	ebeSubtract(double[] a, double[] b) Creates an array whose contents will be the element-by-element subtraction of the second argument from the first.
static boolean	equals(double[] x, double[] y) Returns true iff both arguments are null or have same dimensions and all their elements are equal as defined by Precision.equals(double,double).
static boolean	equals(float[] x, float[] y) Returns true iff both arguments are null or have same dimensions and all their elements are equal as defined by Precision.equals(float,float).
static boolean	equalsIncludingNaN(double[] x, double[] y) Returns true iff both arguments are null or have same dimensions and all their elements are equal as defined by this method.
static boolean	equalsIncludingNaN(float[] x, float[] y) Returns true iff both arguments are null or have same dimensions and all their elements are equal as defined by this method.
static boolean	isMonotonic(double[] val, MathArrays.OrderDirection dir, boolean strict) Check that an array is monotonically increasing or decreasing.
static <T extends Comparable<? super T>> boolean	isMonotonic(T[] val, MathArrays.OrderDirection dir, boolean strict) Check that an array is monotonically increasing or decreasing.
static double	linearCombination(double[] a, double[] b) Compute a linear combination accurately.
static double	linearCombination(double a1, double b1, double a2, double b2) Compute a linear combination accurately.
static double	linearCombination(double a1, double b1, double a2, double b2, double a3, double b3) Compute a linear combination accurately.
static double	linearCombination(double a1, double b1, double a2, double b2, double a3, double b3, double a4, double b4) Compute a linear combination accurately.
static int[]	natural(int n) Returns an array representing the natural number n.
static double[]	normalizeArray(double[] values, double normalizedSum) Normalizes an array to make it sum to a specified value.
static double	safeNorm(double[] v) Returns the Cartesian norm (2-norm), handling both overflow and underflow.
static int[]	sequence(int size, int start, int stride) Returns an array of size integers starting at start, skipping stride numbers.
static void	sortInPlace(double[] x, double[]... yList) Sort an array in ascending order in place and perform the same reordering of entries on other arrays.
static void	sortInPlace(double[] x, MathArrays.OrderDirection dir, double[]... yList) Sort an array in place and perform the same reordering of entries on other arrays.

Methods inherited from class java.lang.Object

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

Method Detail

ebeAdd

public static double[] ebeAdd(double[] a,
                              double[] b)

Creates an array whose contents will be the element-by-element addition of the arguments.

Parameters:

a - First term of the addition.

b - Second term of the addition.

Returns:

a new array r where r[i] = a[i] + b[i].

Throws:

DimensionMismatchException - if the array lengths differ.

Since:

3.1

ebeSubtract

public static double[] ebeSubtract(double[] a,
                                   double[] b)

Creates an array whose contents will be the element-by-element subtraction of the second argument from the first.

Parameters:

a - First term.

b - Element to be subtracted.

Returns:

a new array r where r[i] = a[i] - b[i].

Throws:

DimensionMismatchException - if the array lengths differ.

Since:

3.1

ebeMultiply

public static double[] ebeMultiply(double[] a,
                                   double[] b)

Creates an array whose contents will be the element-by-element multiplication of the arguments.

Parameters:

a - First factor of the multiplication.

b - Second factor of the multiplication.

Returns:

a new array r where r[i] = a[i] * b[i].

Throws:

DimensionMismatchException - if the array lengths differ.

Since:

3.1

ebeDivide

public static double[] ebeDivide(double[] a,
                                 double[] b)

Creates an array whose contents will be the element-by-element division of the first argument by the second.

Parameters:

a - Numerator of the division.

b - Denominator of the division.

Returns:

a new array r where r[i] = a[i] / b[i].

Throws:

DimensionMismatchException - if the array lengths differ.

Since:

3.1

distance1

public static double distance1(double[] p1,
                               double[] p2)

Calculates the L₁ (sum of abs) distance between two points.

Parameters:

p1 - the first point

p2 - the second point

Returns:

the L₁ distance between the two points

distance1

public static int distance1(int[] p1,
                            int[] p2)

Calculates the L₁ (sum of abs) distance between two points.

Parameters:

p1 - the first point

p2 - the second point

Returns:

the L₁ distance between the two points

distance

public static double distance(double[] p1,
                              double[] p2)

Calculates the L₂ (Euclidean) distance between two points.

Parameters:

p1 - the first point

p2 - the second point

Returns:

the L₂ distance between the two points

distance

public static double distance(int[] p1,
                              int[] p2)

Calculates the L₂ (Euclidean) distance between two points.

Parameters:

p1 - the first point

p2 - the second point

Returns:

the L₂ distance between the two points

distanceInf

public static double distanceInf(double[] p1,
                                 double[] p2)

Calculates the L_∞ (max of abs) distance between two points.

Parameters:

p1 - the first point

p2 - the second point

Returns:

the L_∞ distance between the two points

distanceInf

public static int distanceInf(int[] p1,
                              int[] p2)

Calculates the L_∞ (max of abs) distance between two points.

Parameters:

p1 - the first point

p2 - the second point

Returns:

the L_∞ distance between the two points

isMonotonic

public static <T extends Comparable<? super T>> boolean isMonotonic(T[] val,
                                                                    MathArrays.OrderDirection dir,
                                                                    boolean strict)

Check that an array is monotonically increasing or decreasing.

Type Parameters:

T - the type of the elements in the specified array

Parameters:

val - Values.

dir - Ordering direction.

strict - Whether the order should be strict.

Returns:

true if sorted, false otherwise.

isMonotonic

public static boolean isMonotonic(double[] val,
                                  MathArrays.OrderDirection dir,
                                  boolean strict)

Check that an array is monotonically increasing or decreasing.

Parameters:

val - Values.

dir - Ordering direction.

strict - Whether the order should be strict.

Returns:

true if sorted, false otherwise.

checkOrder

public static boolean checkOrder(double[] val,
                                 MathArrays.OrderDirection dir,
                                 boolean strict,
                                 boolean abort)
                          throws NonMonotonicSequenceException

Check that the given array is sorted.

Parameters:

val - Values.

dir - Ordering direction.

strict - Whether the order should be strict.

abort - Whether to throw an exception if the check fails.

Returns:

true if the array is sorted.

Throws:

NonMonotonicSequenceException - if the array is not sorted and abort is true.

checkOrder

public static void checkOrder(double[] val,
                              MathArrays.OrderDirection dir,
                              boolean strict)
                       throws NonMonotonicSequenceException

Check that the given array is sorted.

Parameters:

val - Values.

dir - Ordering direction.

strict - Whether the order should be strict.

Throws:

NonMonotonicSequenceException - if the array is not sorted.

Since:

2.2

checkOrder

public static void checkOrder(double[] val)
                       throws NonMonotonicSequenceException

Check that the given array is sorted in strictly increasing order.

Parameters:

val - Values.

Throws:

NonMonotonicSequenceException - if the array is not sorted.

Since:

2.2

checkRectangular

public static void checkRectangular(long[][] in)
                             throws NullArgumentException,
                                    DimensionMismatchException

Throws DimensionMismatchException if the input array is not rectangular.

Parameters:

in - array to be tested

Throws:

NullArgumentException - if input array is null

DimensionMismatchException - if input array is not rectangular

Since:

3.1

checkPositive

public static void checkPositive(double[] in)
                          throws NotStrictlyPositiveException

Check that all entries of the input array are strictly positive.

Parameters:

in - Array to be tested

Throws:

NotStrictlyPositiveException - if any entries of the array are not strictly positive.

Since:

3.1

checkNonNegative

public static void checkNonNegative(long[] in)
                             throws NotPositiveException

Check that all entries of the input array are >= 0.

Parameters:

in - Array to be tested

Throws:

NotPositiveException - if any array entries are less than 0.

Since:

3.1

checkNonNegative

public static void checkNonNegative(long[][] in)
                             throws NotPositiveException

Check all entries of the input array are >= 0.

Parameters:

in - Array to be tested

Throws:

NotPositiveException - if any array entries are less than 0.

Since:

3.1

safeNorm

public static double safeNorm(double[] v)

Returns the Cartesian norm (2-norm), handling both overflow and underflow. Translation of the minpack enorm subroutine. The redistribution policy for MINPACK is available here, for convenience, it is reproduced below.

Minpack Copyright Notice (1999) University of Chicago. All rights reserved

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
3. The end-user documentation included with the redistribution, if any, must include the following acknowledgment: This product includes software developed by the University of Chicago, as Operator of Argonne National Laboratory. Alternately, this acknowledgment may appear in the software itself, if and wherever such third-party acknowledgments normally appear.
4. WARRANTY DISCLAIMER. THE SOFTWARE IS SUPPLIED "AS IS" WITHOUT WARRANTY OF ANY KIND. THE COPYRIGHT HOLDER, THE UNITED STATES, THE UNITED STATES DEPARTMENT OF ENERGY, AND THEIR EMPLOYEES: (1) DISCLAIM ANY WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE OR NON-INFRINGEMENT, (2) DO NOT ASSUME ANY LEGAL LIABILITY OR RESPONSIBILITY FOR THE ACCURACY, COMPLETENESS, OR USEFULNESS OF THE SOFTWARE, (3) DO NOT REPRESENT THAT USE OF THE SOFTWARE WOULD NOT INFRINGE PRIVATELY OWNED RIGHTS, (4) DO NOT WARRANT THAT THE SOFTWARE WILL FUNCTION UNINTERRUPTED, THAT IT IS ERROR-FREE OR THAT ANY ERRORS WILL BE CORRECTED.
5. LIMITATION OF LIABILITY. IN NO EVENT WILL THE COPYRIGHT HOLDER, THE UNITED STATES, THE UNITED STATES DEPARTMENT OF ENERGY, OR THEIR EMPLOYEES: BE LIABLE FOR ANY INDIRECT, INCIDENTAL, CONSEQUENTIAL, SPECIAL OR PUNITIVE DAMAGES OF ANY KIND OR NATURE, INCLUDING BUT NOT LIMITED TO LOSS OF PROFITS OR LOSS OF DATA, FOR ANY REASON WHATSOEVER, WHETHER SUCH LIABILITY IS ASSERTED ON THE BASIS OF CONTRACT, TORT (INCLUDING NEGLIGENCE OR STRICT LIABILITY), OR OTHERWISE, EVEN IF ANY OF SAID PARTIES HAS BEEN WARNED OF THE POSSIBILITY OF SUCH LOSS OR DAMAGES.

Parameters:

v - Vector of doubles.

Returns:

the 2-norm of the vector.

Since:

2.2

sortInPlace

public static void sortInPlace(double[] x,
                               double[]... yList)
                        throws DimensionMismatchException,
                               NullArgumentException

Sort an array in ascending order in place and perform the same reordering of entries on other arrays. For example, if x = [3, 1, 2], y = [1, 2, 3] and z = [0, 5, 7], then sortInPlace(x, y, z) will update x to [1, 2, 3], y to [2, 3, 1] and z to [5, 7, 0].

Parameters:

x - Array to be sorted and used as a pattern for permutation of the other arrays.

yList - Set of arrays whose permutations of entries will follow those performed on x.

Throws:

DimensionMismatchException - if any y is not the same size as x.

NullArgumentException - if x or any y is null.

Since:

3.0

sortInPlace

public static void sortInPlace(double[] x,
                               MathArrays.OrderDirection dir,
                               double[]... yList)
                        throws NullArgumentException,
                               DimensionMismatchException

Sort an array in place and perform the same reordering of entries on other arrays. This method works the same as the other sortInPlace method, but allows the order of the sort to be provided in the dir parameter.

Parameters:

x - Array to be sorted and used as a pattern for permutation of the other arrays.

dir - Order direction.

yList - Set of arrays whose permutations of entries will follow those performed on x.

Throws:

DimensionMismatchException - if any y is not the same size as x.

NullArgumentException - if x or any y is null

Since:

3.0

copyOf

public static int[] copyOf(int[] source)

Creates a copy of the source array.

Parameters:

source - Array to be copied.

Returns:

the copied array.

copyOf

public static double[] copyOf(double[] source)

Creates a copy of the source array.

Parameters:

source - Array to be copied.

Returns:

the copied array.

copyOf

public static int[] copyOf(int[] source,
                           int len)

Creates a copy of the source array.

Parameters:

source - Array to be copied.

len - Number of entries to copy. If smaller then the source length, the copy will be truncated, if larger it will padded with zeroes.

Returns:

the copied array.

copyOf

public static double[] copyOf(double[] source,
                              int len)

Creates a copy of the source array.

Parameters:

source - Array to be copied.

len - Number of entries to copy. If smaller then the source length, the copy will be truncated, if larger it will padded with zeroes.

Returns:

the copied array.

linearCombination

public static double linearCombination(double[] a,
                                       double[] b)
                                throws DimensionMismatchException

Compute a linear combination accurately. This method computes the sum of the products ai bi to high accuracy. It does so by using specific multiplication and addition algorithms to preserve accuracy and reduce cancellation effects.
It is based on the 2005 paper Accurate Sum and Dot Product by Takeshi Ogita, Siegfried M. Rump, and Shin'ichi Oishi published in SIAM J. Sci. Comput.

Parameters:

a - Factors.

b - Factors.

Returns:

Σi ai bi.

Throws:

DimensionMismatchException - if arrays dimensions don't match

linearCombination

public static double linearCombination(double a1,
                                       double b1,
                                       double a2,
                                       double b2)

Compute a linear combination accurately.

This method computes a₁×b₁ + a₂×b₂ to high accuracy. It does so by using specific multiplication and addition algorithms to preserve accuracy and reduce cancellation effects. It is based on the 2005 paper Accurate Sum and Dot Product by Takeshi Ogita, Siegfried M. Rump, and Shin'ichi Oishi published in SIAM J. Sci. Comput.

Parameters:

a1 - first factor of the first term

b1 - second factor of the first term

a2 - first factor of the second term

b2 - second factor of the second term

Returns:

a₁×b₁ + a₂×b₂

See Also:

linearCombination(double, double, double, double, double, double), linearCombination(double, double, double, double, double, double, double, double)

linearCombination

public static double linearCombination(double a1,
                                       double b1,
                                       double a2,
                                       double b2,
                                       double a3,
                                       double b3)

Compute a linear combination accurately.

This method computes a₁×b₁ + a₂×b₂ + a₃×b₃ to high accuracy. It does so by using specific multiplication and addition algorithms to preserve accuracy and reduce cancellation effects. It is based on the 2005 paper Accurate Sum and Dot Product by Takeshi Ogita, Siegfried M. Rump, and Shin'ichi Oishi published in SIAM J. Sci. Comput.

Parameters:

a1 - first factor of the first term

b1 - second factor of the first term

a2 - first factor of the second term

b2 - second factor of the second term

a3 - first factor of the third term

b3 - second factor of the third term

Returns:

a₁×b₁ + a₂×b₂ + a₃×b₃

See Also:

linearCombination(double, double, double, double), linearCombination(double, double, double, double, double, double, double, double)

linearCombination

public static double linearCombination(double a1,
                                       double b1,
                                       double a2,
                                       double b2,
                                       double a3,
                                       double b3,
                                       double a4,
                                       double b4)

Compute a linear combination accurately.

This method computes a₁×b₁ + a₂×b₂ + a₃×b₃ + a₄×b₄ to high accuracy. It does so by using specific multiplication and addition algorithms to preserve accuracy and reduce cancellation effects. It is based on the 2005 paper Accurate Sum and Dot Product by Takeshi Ogita, Siegfried M. Rump, and Shin'ichi Oishi published in SIAM J. Sci. Comput.

Parameters:

a1 - first factor of the first term

b1 - second factor of the first term

a2 - first factor of the second term

b2 - second factor of the second term

a3 - first factor of the third term

b3 - second factor of the third term

a4 - first factor of the third term

b4 - second factor of the third term

Returns:

a₁×b₁ + a₂×b₂ + a₃×b₃ + a₄×b₄

See Also:

linearCombination(double, double, double, double), linearCombination(double, double, double, double, double, double)

equals

public static boolean equals(float[] x,
                             float[] y)

Returns true iff both arguments are null or have same dimensions and all their elements are equal as defined by Precision.equals(float,float).

Parameters:

x - first array

y - second array

Returns:

true if the values are both null or have same dimension and equal elements.

equalsIncludingNaN

public static boolean equalsIncludingNaN(float[] x,
                                         float[] y)

Returns true iff both arguments are null or have same dimensions and all their elements are equal as defined by this method.

Parameters:

x - first array

y - second array

Returns:

true if the values are both null or have same dimension and equal elements

Since:

2.2

equals

public static boolean equals(double[] x,
                             double[] y)

Returns true iff both arguments are null or have same dimensions and all their elements are equal as defined by Precision.equals(double,double).

Parameters:

x - First array.

y - Second array.

Returns:

true if the values are both null or have same dimension and equal elements.

equalsIncludingNaN

public static boolean equalsIncludingNaN(double[] x,
                                         double[] y)

Returns true iff both arguments are null or have same dimensions and all their elements are equal as defined by this method.

Parameters:

x - First array.

y - Second array.

Returns:

true if the values are both null or have same dimension and equal elements.

Since:

2.2

normalizeArray

public static double[] normalizeArray(double[] values,
                                      double normalizedSum)
                               throws MathIllegalArgumentException,
                                      MathArithmeticException

Normalizes an array to make it sum to a specified value. Returns the result of the transformation

    x |-> x * normalizedSum / sum
 

applied to each non-NaN element x of the input array, where sum is the sum of the non-NaN entries in the input array.

Throws IllegalArgumentException if normalizedSum is infinite or NaN and ArithmeticException if the input array contains any infinite elements or sums to 0.

Ignores (i.e., copies unchanged to the output array) NaNs in the input array.

Parameters:

values - Input array to be normalized

normalizedSum - Target sum for the normalized array

Returns:

the normalized array.

Throws:

MathArithmeticException - if the input array contains infinite elements or sums to zero.

MathIllegalArgumentException - if the target sum is infinite or NaN.

Since:

2.1

buildArray

public static <T> T[] buildArray(Field<T> field,
                                 int length)

Build an array of elements.

Arrays are filled with field.getZero()

Type Parameters:

T - the type of the field elements

Parameters:

field - field to which array elements belong

length - of the array

Returns:

a new array

Since:

3.2

buildArray

public static <T> T[][] buildArray(Field<T> field,
                                   int rows,
                                   int columns)

Build a double dimension array of elements.

Arrays are filled with field.getZero()

Type Parameters:

T - the type of the field elements

Parameters:

field - field to which array elements belong

rows - number of rows in the array

columns - number of columns (may be negative to build partial arrays in the same way new Field[rows][] works)

Returns:

a new array

Since:

3.2

natural

public static int[] natural(int n)

Returns an array representing the natural number n.

Parameters:

n - Natural number.

Returns:

an array whose entries are the numbers 0, 1, ..., n-1. If n == 0, the returned array is empty.

sequence

public static int[] sequence(int size,
                             int start,
                             int stride)

Returns an array of size integers starting at start, skipping stride numbers.

Parameters:

size - Natural number.

start - Natural number.

stride - Natural number.

Returns:

an array whose entries are the numbers start, start + stride, ..., start + (size - 1) * stride. If size == 0, the returned array is empty.

Since:

3.4