Package org.jblas

Class DoubleMatrix

  • All Implemented Interfaces:
    java.io.Serializable

    public class DoubleMatrix
    extends java.lang.Object
    implements java.io.Serializable
    A general matrix class for double typed values. Don't be intimidated by the large number of methods this function defines. Most are overloads provided for ease of use. For example, for each arithmetic operation, up to six overloaded versions exist to handle in-place computations, and scalar arguments (like adding a number to all elements of a matrix).

    Construction

    To construct a two-dimensional matrices, you can use the following constructors and static methods.

    MethodDescription
    DoubleMatrix(m,n, [value1, value2, value3...])Values are filled in column by column.
    DoubleMatrix(new double[][] {{value1, value2, ...}, ...}Inner arrays are rows.
    DoubleMatrix.zeros(m,n) Initial values set to 0.0.
    DoubleMatrix.ones(m,n) Initial values set to 1.0.
    DoubleMatrix.rand(m,n) Values drawn at random between 0.0 and 1.0.
    DoubleMatrix.randn(m,n) Values drawn from normal distribution.
    DoubleMatrix.eye(n) Unit matrix (values 0.0 except for 1.0 on the diagonal).
    DoubleMatrix.diag(array) Diagonal matrix with given diagonal elements.
    Matrix constructors.

    Alternatively, you can construct (column) vectors, if you just supply the length using the following constructors and static methods.

    Method Description
    DoubleMatrix(m) Constructs a column vector.
    DoubleMatrix(new double[] {value1, value2, ...})Constructs a column vector.
    DoubleMatrix.zeros(m) Initial values set to 0.0.
    DoubleMatrix.ones(m) Initial values set to 1.0.
    DoubleMatrix.rand(m) Values drawn at random between 0.0 and 1.0.
    DoubleMatrix.randn(m) Values drawn from normal distribution.
    DoubleMatrix.linspace(a, b, n)n linearly spaced values from a to b.
    DoubleMatrix.logspace(a, b, n)n logarithmically spaced values form 10^a to 10^b.
    Column vector constructors.

    You can also construct new matrices by concatenating matrices either horziontally or vertically:

    MethodDescription
    x.concatHorizontally(y)New matrix will be x next to y.
    x.concatVertically(y)New matrix will be x atop y.
    Matrix concatenation.

    Element Access, Copying and Duplication

    To access individual elements, or whole rows and columns, use the following methods:

    x.MethodDescription
    x.get(i,j)Get element in row i and column j.
    x.put(i, j, v)Set element in row i and column j to value v
    x.get(i)Get the ith element of the matrix (traversing rows first).
    x.put(i, v)Set the ith element of the matrix (traversing rows first).
    x.getColumn(i)Get a copy of column i.
    x.putColumn(i, c)Put matrix c into column i.
    x.getRow(i)Get a copy of row i.
    x.putRow(i, c)Put matrix c into row i.
    x.swapColumns(i, j)Swap the contents of columns i and j.
    x.swapRows(i, j)Swap the contents of rows i and j.
    Element access.

    For get and put, you can also pass integer arrays, DoubleMatrix objects, or Range objects, which then specify the indices used as follows:

    • integer array: the elements will be used as indices.
    • DoubleMatrix object: non-zero entries specify the indices.
    • Range object: see below.

    When using put with multiple indices, the assigned object must have the correct size or be a scalar.

    There exist the following Range objects. The Class RangeUtils also contains the a number of handy helper methods for constructing these ranges.

    Class RangeUtils method Indices
    AllRange all() All legal indices.
    PointRange point(i) A single point.
    IntervalRange interval(a, b) All indices from a to b (inclusive)
    IndicesRange indices(int[]) The specified indices.
    indices(DoubleMatrix)The specified indices.
    find(DoubleMatrix)The non-zero entries of the matrix.
    Range objects.

    The following methods can be used for duplicating and copying matrices.

    MethodDescription
    x.dup()Get a copy of x.
    x.copy(y)Copy the contents of y to x (possible resizing x).
    Copying matrices.

    Size and Shape

    The following methods permit to access the size of a matrix and change its size or shape.

    x.MethodDescription
    x.rowsNumber of rows.
    x.columnsNumber of columns.
    x.lengthTotal number of elements.
    x.isEmpty()Checks whether rows == 0 and columns == 0.
    x.isRowVector()Checks whether rows == 1.
    x.isColumnVector()Checks whether columns == 1.
    x.isVector()Checks whether rows == 1 or columns == 1.
    x.isSquare()Checks whether rows == columns.
    x.isScalar()Checks whether length == 1.
    x.resize(r, c)Resize the matrix to r rows and c columns, discarding the content.
    x.reshape(r, c)Resize the matrix to r rows and c columns.
    Number of elements must not change.
    Size and size checks.

    The size is stored in the rows and columns member variables. The total number of elements is stored in length. Do not change these values unless you know what you're doing!

    Arithmetics

    The usual arithmetic operations are implemented. Each operation exists in a in-place version, recognizable by the suffix "i", to which you can supply the result matrix (or this is used, if missing). Using in-place operations can also lead to a smaller memory footprint, as the number of temporary objects is reduced (although the JVM garbage collector is usually pretty good at reusing these temporary object immediately with little overhead.)

    Whenever you specify a result vector, the result vector must already have the correct dimensions.

    For example, you can add two matrices using the add method. If you want to store the result in of x + y in z, type x.addi(y, z) // computes x = y + z. Even in-place methods return the result, such that you can easily chain in-place methods, for example: x.addi(y).addi(z) // computes x += y; x += z

    Methods which operate element-wise only make sure that the length of the matrices is correct. Therefore, you can add a 3 * 3 matrix to a 1 * 9 matrix, for example.

    Finally, there exist versions which take doubles instead of DoubleMatrix Objects as arguments. These then compute the operation with the same value as the right-hand-side. The same effect can be achieved by passing a DoubleMatrix with exactly one element.

    Operation Method Comment
    x + y x.add(y)
    x - y x.sub(y), y.rsub(x) rsub subtracts left from right hand side
    x * y x.mul(y) element-wise multiplication
    x.mmul(y)matrix-matrix multiplication
    x.dot(y) scalar-product
    x / y x.div(y), y.rdiv(x) rdiv divides right hand side by left hand side.
    - x x.neg()
    Basic arithmetics.

    There also exist operations which work on whole columns or rows.

    Method Description
    x.addRowVector adds a vector to each row (addiRowVector works in-place)
    x.addColumnVectoradds a vector to each column
    x.subRowVector subtracts a vector from each row
    x.subColumnVectorsubtracts a vector from each column
    x.mulRowVector Multiplies each row by a vector (elementwise)
    x.mulColumnVectorMultiplies each column by a vector (elementwise)
    x.divRowVector Divide each row by a vector (elementwise)
    x.divColumnVectorDivide each column by a vector (elementwise)
    x.mulRow Multiplies a row by a scalar
    x.mulColumn Multiplies a column by a scalar
    Row and column arithmetics.

    In principle, you could achieve the same result by first calling getColumn(), adding, and then calling putColumn, but these methods are much faster.

    The following comparison operations are available

    Operation Method
    x < y x.lt(y)
    x <= y x.le(y)
    x > y x.gt(y)
    x >= y x.ge(y)
    x == y x.eq(y)
    x != y x.ne(y)
    Comparison operations.

    Logical operations are also supported. For these operations, a value different from zero is treated as "true" and zero is treated as "false". All operations are carried out elementwise.

    Operation Method
    x & y x.and(y)
    x | y x.or(y)
    x ^ y x.xor(y)
    ! x x.not()
    Logical operations.

    Finally, there are a few more methods to compute various things:

    Method Description
    x.max() Return maximal element
    x.argmax() Return index of largest element
    x.min() Return minimal element
    x.argmin() Return index of smallest element
    x.columnMins() Return column-wise minima
    x.columnArgmins() Return column-wise index of minima
    x.columnMaxs() Return column-wise maxima
    x.columnArgmaxs() Return column-wise index of maxima
    Minimum and maximum.
    Author:
    Mikio Braun, Johannes Schaback
    See Also:
    Serialized Form
    • Field Detail

      • rows

        public int rows
        Number of rows.
      • columns

        public int columns
        Number of columns.
      • length

        public int length
        Total number of elements (for convenience).
      • data

        public double[] data
        The actual data stored by rows (that is, row 0, row 1...).
    • Constructor Detail

      • DoubleMatrix

        public DoubleMatrix​(int newRows,
                            int newColumns,
                            double... newData)
        Create a new matrix with newRows rows, newColumns columns using newData as the data. Note that any change to the DoubleMatrix will change the input array, too.
        Parameters:
        newRows - the number of rows of the new matrix
        newColumns - the number of columns of the new matrix
        newData - the data array to be used. Data must be stored by column (column-major)
      • DoubleMatrix

        public DoubleMatrix​(int newRows,
                            int newColumns)
        Creates a new n times m DoubleMatrix.
        Parameters:
        newRows - the number of rows (n) of the new matrix.
        newColumns - the number of columns (m) of the new matrix.
      • DoubleMatrix

        public DoubleMatrix()
        Creates a new DoubleMatrix of size 0 times 0.
      • DoubleMatrix

        public DoubleMatrix​(int len)
        Create a Matrix of length len. This creates a column vector.
        Parameters:
        len -
      • DoubleMatrix

        public DoubleMatrix​(double[] newData)
        Create a a column vector using newData as the data array. Note that any change to the created DoubleMatrix will change in input array.
      • DoubleMatrix

        public DoubleMatrix​(java.lang.String filename)
                     throws java.io.IOException
        Creates a new matrix by reading it from a file.
        Parameters:
        filename - the path and name of the file to read the matrix from
        Throws:
        java.io.IOException
      • DoubleMatrix

        public DoubleMatrix​(double[][] data)
        Creates a new n times m DoubleMatrix from the given n times m 2D data array. Note that the input array is copied and any change to the DoubleMatrix will not change the input array. The first dimension of the array makes the rows (n) and the second dimension the columns (m). For example, the given code

        new DoubleMatrix(new double[][]{{1d, 2d, 3d}, {4d, 5d, 6d}, {7d, 8d, 9d}}).print();

        will constructs the following matrix:
         1.0    2.0     3.0
         4.0    5.0     6.0
         7.0    8.0     9.0
         
        .
        Parameters:
        data - n times m data array
      • DoubleMatrix

        public DoubleMatrix​(java.util.List<java.lang.Double> data)
        Creates a DoubleMatrix column vector from the given List<Double>.
        Parameters:
        data - data from which the entries are taken.