Class DoubleMatrix

  • All Implemented Interfaces:
    Matrix, java.io.Serializable, Bean, ImmutableBean

    public final class DoubleMatrix
    extends java.lang.Object
    implements Matrix, java.io.Serializable, ImmutableBean
    An immutable two-dimensional array of double values.

    This provides functionality similar to List but for a rectangular double[][].

    In mathematical terms, this is a two-dimensional matrix.

    See Also:
    Serialized Form
    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  DoubleMatrix.Meta
      The meta-bean for DoubleMatrix.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static DoubleMatrix EMPTY
      An empty array.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      DoubleArray column​(int column)
      Gets the column at the specified index.
      double[] columnArray​(int column)
      Gets the column at the specified index as an independent array.
      int columnCount()
      Gets the number of columns of this matrix.
      DoubleMatrix combine​(DoubleMatrix other, java.util.function.DoubleBinaryOperator operator)
      Returns an instance where each element is formed by some combination of the matching values in this matrix and the other matrix.
      static DoubleMatrix copyOf​(double[][] array)
      Obtains an instance from a double[][].
      static DoubleMatrix diagonal​(DoubleArray array)
      Obtains a diagonal matrix from the specified array.
      int dimensions()
      Gets the number of dimensions of this matrix.
      boolean equals​(java.lang.Object obj)  
      static DoubleMatrix filled​(int rows, int columns)
      Obtains an instance with all entries equal to the zero.
      static DoubleMatrix filled​(int rows, int columns, double value)
      Obtains an instance with all entries equal to the same value.
      void forEach​(IntIntDoubleConsumer action)
      Applies an action to each value in the matrix.
      double get​(int row, int column)
      Gets the value at the specified row and column in this matrix.
      int hashCode()  
      static DoubleMatrix identity​(int size)
      Obtains an identity matrix.
      boolean isEmpty()
      Checks if this matrix is empty.
      boolean isSquare()
      Checks if this matrix is square.
      DoubleMatrix map​(java.util.function.DoubleUnaryOperator operator)
      Returns an instance with an operation applied to each value in the matrix.
      DoubleMatrix mapWithIndex​(IntIntDoubleToDoubleFunction function)
      Returns an instance with an operation applied to each indexed value in the matrix.
      static DoubleMatrix.Meta meta()
      The meta-bean for DoubleMatrix.
      DoubleMatrix.Meta metaBean()  
      DoubleMatrix minus​(DoubleMatrix other)
      Returns an instance where each element is equal to the difference between the matching values in this matrix and the other matrix.
      DoubleMatrix multipliedBy​(double factor)
      Returns an instance with each value multiplied by the specified factor.
      static DoubleMatrix of()
      Obtains an empty instance.
      static DoubleMatrix of​(int rows, int columns, double... values)
      Obtains an immutable array with the specified size and values.
      static DoubleMatrix of​(int rows, int columns, IntIntToDoubleFunction valueFunction)
      Obtains an instance with entries filled using a function.
      static DoubleMatrix ofArrayObjects​(int rows, int columns, java.util.function.IntFunction<DoubleArray> valuesFunction)
      Obtains an instance with entries filled using a function.
      static DoubleMatrix ofArrays​(int rows, int columns, java.util.function.IntFunction<double[]> valuesFunction)
      Obtains an instance with entries filled using a function.
      static DoubleMatrix ofUnsafe​(double[][] array)
      Obtains an instance by wrapping a double[][].
      DoubleMatrix plus​(DoubleMatrix other)
      Returns an instance where each element is the sum of the matching values in this array and the other matrix.
      double reduce​(double identity, java.util.function.DoubleBinaryOperator operator)
      Reduces this matrix returning a single value.
      DoubleArray row​(int row)
      Gets the row at the specified index.
      double[] rowArray​(int row)
      Gets the row at the specified index as an independent array.
      int rowCount()
      Gets the number of rows of this matrix.
      int size()
      Gets the size of this matrix.
      double[][] toArray()
      Converts this instance to an independent double[][].
      double[][] toArrayUnsafe()
      Returns the underlying array.
      java.lang.String toString()  
      double total()
      Returns the total of all the values in the matrix.
      DoubleMatrix transpose()
      Transposes the matrix.
      DoubleMatrix with​(int row, int column, double newValue)
      Returns an instance with the value at the specified index changed.
      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait
    • Field Detail

      • EMPTY

        public static final DoubleMatrix EMPTY
        An empty array.
    • Method Detail

      • of

        public static DoubleMatrix of()
        Obtains an empty instance.
        Returns:
        the empty immutable matrix
      • of

        public static DoubleMatrix of​(int rows,
                                      int columns,
                                      double... values)
        Obtains an immutable array with the specified size and values.

        The first two arguments specify the size. The remaining arguments specify the values, all of row 0, then row 1, and so on. There must be be rows * columns values.

        Parameters:
        rows - the number of rows
        columns - the number of columns
        values - the values
        Returns:
        an array containing the specified value
        Throws:
        java.lang.IllegalArgumentException - if the values array if the incorrect length
      • of

        public static DoubleMatrix of​(int rows,
                                      int columns,
                                      IntIntToDoubleFunction valueFunction)
        Obtains an instance with entries filled using a function.

        The function is passed the row and column index, returning the value.

        Parameters:
        rows - the number of rows
        columns - the number of columns
        valueFunction - the function used to populate the value
        Returns:
        a matrix initialized using the function
      • ofArrays

        public static DoubleMatrix ofArrays​(int rows,
                                            int columns,
                                            java.util.function.IntFunction<double[]> valuesFunction)
        Obtains an instance with entries filled using a function.

        The function is passed the row index, returning the column values.

        Parameters:
        rows - the number of rows
        columns - the number of columns
        valuesFunction - the function used to populate the values
        Returns:
        a matrix initialized using the function
      • ofArrayObjects

        public static DoubleMatrix ofArrayObjects​(int rows,
                                                  int columns,
                                                  java.util.function.IntFunction<DoubleArray> valuesFunction)
        Obtains an instance with entries filled using a function.

        The function is passed the row index, returning the column values.

        Parameters:
        rows - the number of rows
        columns - the number of columns
        valuesFunction - the function used to populate the values
        Returns:
        a matrix initialized using the function
      • ofUnsafe

        public static DoubleMatrix ofUnsafe​(double[][] array)
        Obtains an instance by wrapping a double[][].

        This method is inherently unsafe as it relies on good behavior by callers. Callers must never make any changes to the passed in array after calling this method. Doing so would violate the immutability of this class.

        The double[][] must be rectangular, with the same length for each row. This is not validated.

        Parameters:
        array - the array to assign
        Returns:
        a matrix wrapping the specified array
      • copyOf

        public static DoubleMatrix copyOf​(double[][] array)
        Obtains an instance from a double[][].

        The input array is copied and not mutated.

        Parameters:
        array - the array to copy, cloned
        Returns:
        a matrix containing the specified values
      • filled

        public static DoubleMatrix filled​(int rows,
                                          int columns)
        Obtains an instance with all entries equal to the zero.
        Parameters:
        rows - the number of rows
        columns - the number of columns
        Returns:
        a matrix filled with zeroes
      • filled

        public static DoubleMatrix filled​(int rows,
                                          int columns,
                                          double value)
        Obtains an instance with all entries equal to the same value.
        Parameters:
        rows - the number of rows
        columns - the number of columns
        value - the value of all the elements
        Returns:
        a matrix filled with the specified value
      • identity

        public static DoubleMatrix identity​(int size)
        Obtains an identity matrix.

        An identity matrix is square. It has every value equal to zero, except those on the primary diagonal, which are one.

        Parameters:
        size - the size of the matrix
        Returns:
        an identity matrix of the specified size
      • diagonal

        public static DoubleMatrix diagonal​(DoubleArray array)
        Obtains a diagonal matrix from the specified array.

        A diagonal matrix is square. It only has values on the primary diagonal, and those values are taken from the specified array.

        Parameters:
        array - the array to use to create the matrix
        Returns:
        an identity matrix of the specified size
      • dimensions

        public int dimensions()
        Gets the number of dimensions of this matrix.
        Specified by:
        dimensions in interface Matrix
        Returns:
        two
      • size

        public int size()
        Gets the size of this matrix.

        This is the total number of elements.

        Specified by:
        size in interface Matrix
        Returns:
        the matrix size, zero or greater
      • rowCount

        public int rowCount()
        Gets the number of rows of this matrix.
        Returns:
        the number of rows
      • columnCount

        public int columnCount()
        Gets the number of columns of this matrix.
        Returns:
        the number of columns
      • isSquare

        public boolean isSquare()
        Checks if this matrix is square.

        A square matrix has the same number of rows and columns.

        Returns:
        true if square
      • isEmpty

        public boolean isEmpty()
        Checks if this matrix is empty.
        Returns:
        true if empty
      • get

        public double get​(int row,
                          int column)
        Gets the value at the specified row and column in this matrix.
        Parameters:
        row - the zero-based row index to retrieve
        column - the zero-based column index to retrieve
        Returns:
        the value at the row and column
        Throws:
        java.lang.IndexOutOfBoundsException - if either index is invalid
      • row

        public DoubleArray row​(int row)
        Gets the row at the specified index.
        Parameters:
        row - the zero-based row index to retrieve
        Returns:
        the row
      • rowArray

        public double[] rowArray​(int row)
        Gets the row at the specified index as an independent array.
        Parameters:
        row - the zero-based row index to retrieve
        Returns:
        the row as a cloned array
      • column

        public DoubleArray column​(int column)
        Gets the column at the specified index.
        Parameters:
        column - the zero-based column index to retrieve
        Returns:
        the column
      • columnArray

        public double[] columnArray​(int column)
        Gets the column at the specified index as an independent array.
        Parameters:
        column - the zero-based column index to retrieve
        Returns:
        the column as a cloned array
      • toArray

        public double[][] toArray()
        Converts this instance to an independent double[][].
        Returns:
        an array of arrays containing a copy of matrix elements
      • toArrayUnsafe

        public double[][] toArrayUnsafe()
        Returns the underlying array.

        This method is inherently unsafe as it relies on good behavior by callers. Callers must never make any changes to the array returned by this method. Doing so would violate the immutability of this class.

        Returns:
        the raw array
      • forEach

        public void forEach​(IntIntDoubleConsumer action)
        Applies an action to each value in the matrix.

        This is used to perform an action on the contents of this matrix. The action receives the row, the column and the value. For example, the action could print out the matrix.

           base.forEach((row, col, value) -> System.out.println(row + ": " + col + ": " + value));
         

        This instance is immutable and unaffected by this method.

        Parameters:
        action - the action to be applied
      • with

        public DoubleMatrix with​(int row,
                                 int column,
                                 double newValue)
        Returns an instance with the value at the specified index changed.

        This instance is immutable and unaffected by this method.

        Parameters:
        row - the zero-based row index to retrieve
        column - the zero-based column index to retrieve
        newValue - the new value to store
        Returns:
        a copy of this matrix with the value at the index changed
        Throws:
        java.lang.IndexOutOfBoundsException - if either index is invalid
      • multipliedBy

        public DoubleMatrix multipliedBy​(double factor)
        Returns an instance with each value multiplied by the specified factor.

        This is used to multiply the contents of this matrix, returning a new matrix.

        This is a special case of map(DoubleUnaryOperator). This instance is immutable and unaffected by this method.

        Parameters:
        factor - the multiplicative factor
        Returns:
        a copy of this matrix with the each value multiplied by the factor
      • map

        public DoubleMatrix map​(java.util.function.DoubleUnaryOperator operator)
        Returns an instance with an operation applied to each value in the matrix.

        This is used to perform an operation on the contents of this matrix, returning a new matrix. The operator only receives the value. For example, the operator could take the inverse of each element.

           result = base.map(value -> 1 / value);
         

        This instance is immutable and unaffected by this method.

        Parameters:
        operator - the operator to be applied
        Returns:
        a copy of this matrix with the operator applied to the original values
      • mapWithIndex

        public DoubleMatrix mapWithIndex​(IntIntDoubleToDoubleFunction function)
        Returns an instance with an operation applied to each indexed value in the matrix.

        This is used to perform an operation on the contents of this matrix, returning a new matrix. The function receives the row index, column index and the value. For example, the operator could multiply the value by the index.

           result = base.mapWithIndex((index, value) -> index * value);
         

        This instance is immutable and unaffected by this method.

        Parameters:
        function - the function to be applied
        Returns:
        a copy of this matrix with the operator applied to the original values
      • plus

        public DoubleMatrix plus​(DoubleMatrix other)
        Returns an instance where each element is the sum of the matching values in this array and the other matrix.

        This is used to add two matrices, returning a new matrix. Element (i,j) in the resulting matrix is equal to element (i,j) in this matrix plus element (i,j) in the other matrix. The matrices must be of the same size.

        This is a special case of combine(DoubleMatrix, DoubleBinaryOperator). This instance is immutable and unaffected by this method.

        Parameters:
        other - the other matrix
        Returns:
        a copy of this matrix with matching elements added
        Throws:
        java.lang.IllegalArgumentException - if the matrices have different sizes
      • minus

        public DoubleMatrix minus​(DoubleMatrix other)
        Returns an instance where each element is equal to the difference between the matching values in this matrix and the other matrix.

        This is used to subtract the second matrix from the first, returning a new matrix. Element (i,j) in the resulting matrix is equal to element (i,j) in this matrix minus element (i,j) in the other matrix. The matrices must be of the same size.

        This is a special case of combine(DoubleMatrix, DoubleBinaryOperator). This instance is immutable and unaffected by this method.

        Parameters:
        other - the other matrix
        Returns:
        a copy of this matrix with matching elements subtracted
        Throws:
        java.lang.IllegalArgumentException - if the matrices have different sizes
      • combine

        public DoubleMatrix combine​(DoubleMatrix other,
                                    java.util.function.DoubleBinaryOperator operator)
        Returns an instance where each element is formed by some combination of the matching values in this matrix and the other matrix.

        This is used to combine two matrices, returning a new matrix. Element (i,j) in the resulting matrix is equal to the result of the operator when applied to element (i,j) in this array and element (i,j) in the other array. The arrays must be of the same size.

        This instance is immutable and unaffected by this method.

        Parameters:
        other - the other matrix
        operator - the operator used to combine each pair of values
        Returns:
        a copy of this matrix combined with the specified matrix
        Throws:
        java.lang.IllegalArgumentException - if the matrices have different sizes
      • total

        public double total()
        Returns the total of all the values in the matrix.

        This is a special case of reduce(double, DoubleBinaryOperator).

        Returns:
        the total of all the values
      • reduce

        public double reduce​(double identity,
                             java.util.function.DoubleBinaryOperator operator)
        Reduces this matrix returning a single value.

        This is used to reduce the values in this matrix to a single value. The operator is called once for each element in the matrix. The first argument to the operator is the running total of the reduction, starting from zero. The second argument to the operator is the element.

        This instance is immutable and unaffected by this method.

        Parameters:
        identity - the identity value to start from
        operator - the operator used to combine the value with the current total
        Returns:
        the result of the reduction
      • transpose

        public DoubleMatrix transpose()
        Transposes the matrix.

        This converts a matrix of m x n into a matrix of n x m. Each element is moved to the opposite position.

        Returns:
        the transposed matrix
      • equals

        public boolean equals​(java.lang.Object obj)
        Overrides:
        equals in class java.lang.Object
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
      • meta

        public static DoubleMatrix.Meta meta()
        The meta-bean for DoubleMatrix.
        Returns:
        the meta-bean, not null