DiagonalMatrix (Apache Commons Math 3.3 API)

org.apache.commons.math3.linear

## Class DiagonalMatrix

- java.lang.Object
- - org.apache.commons.math3.linear.RealLinearOperator
  - - org.apache.commons.math3.linear.AbstractRealMatrix
    - - org.apache.commons.math3.linear.DiagonalMatrix

- All Implemented Interfaces:
    Serializable, AnyMatrix, RealMatrix

      public class DiagonalMatrix
      extends AbstractRealMatrix
      implements Serializable

  Implementation of a diagonal matrix.
  Since:
    3.1.1
  Version:
    $Id: DiagonalMatrix.java 1533638 2013-10-18 21:19:18Z tn $
  See Also:
    Serialized Form

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `DiagonalMatrix(double[] d)` Creates a matrix using the input array as the underlying data.
    `DiagonalMatrix(double[] d, boolean copyArray)` Creates a matrix using the input array as the underlying data.
    `DiagonalMatrix(int dimension)` Creates a matrix with the supplied dimension.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `DiagonalMatrix` | `add(DiagonalMatrix m)` Compute the sum of `this` and `m`.
    `void` | `addToEntry(int row, int column, double increment)` Adds (in place) the specified value to the specified entry of `this` matrix.
    `RealMatrix` | `copy()` Returns a (deep) copy of this.
    `RealMatrix` | `createMatrix(int rowDimension, int columnDimension)` Create a new RealMatrix of the same type as the instance with the supplied row and column dimensions.
    `int` | `getColumnDimension()` Returns the number of columns of this matrix.
    `double[][]` | `getData()` Returns matrix entries as a two-dimensional array.
    `double[]` | `getDataRef()` Gets a reference to the underlying data array.
    `double` | `getEntry(int row, int column)` Get the entry in the specified row and column.
    `int` | `getRowDimension()` Returns the number of rows of this matrix.
    `DiagonalMatrix` | `inverse()` Computes the inverse of this diagonal matrix.
    `DiagonalMatrix` | `inverse(double threshold)` Computes the inverse of this diagonal matrix.
    `boolean` | `isSingular(double threshold)` Returns whether this diagonal matrix is singular, i.e.
    `DiagonalMatrix` | `multiply(DiagonalMatrix m)` Returns the result of postmultiplying `this` by `m`.
    `RealMatrix` | `multiply(RealMatrix m)` Returns the result of postmultiplying `this` by `m`.
    `void` | `multiplyEntry(int row, int column, double factor)` Multiplies (in place) the specified entry of `this` matrix by the specified value.
    `double[]` | `operate(double[] v)` Returns the result of multiplying this by the vector `v`.
    `double[]` | `preMultiply(double[] v)` Returns the (row) vector result of premultiplying this by the vector `v`.
    `RealVector` | `preMultiply(RealVector v)` Returns the (row) vector result of premultiplying this by the vector `v`.
    `void` | `setEntry(int row, int column, double value)` Set the entry in the specified row and column.
    `DiagonalMatrix` | `subtract(DiagonalMatrix m)` Returns `this` minus `m`.

    - ### Methods inherited from class org.apache.commons.math3.linear.AbstractRealMatrix

      `add, copySubMatrix, copySubMatrix, equals, getColumn, getColumnMatrix, getColumnVector, getFrobeniusNorm, getNorm, getRow, getRowMatrix, getRowVector, getSubMatrix, getSubMatrix, getTrace, hashCode, isSquare, operate, power, preMultiply, scalarAdd, scalarMultiply, setColumn, setColumnMatrix, setColumnVector, setRow, setRowMatrix, setRowVector, setSubMatrix, subtract, toString, transpose, walkInColumnOrder, walkInColumnOrder, walkInColumnOrder, walkInColumnOrder, walkInOptimizedOrder, walkInOptimizedOrder, walkInOptimizedOrder, walkInOptimizedOrder, walkInRowOrder, walkInRowOrder, walkInRowOrder, walkInRowOrder`

    - ### Methods inherited from class org.apache.commons.math3.linear.RealLinearOperator

      `isTransposable, operateTranspose`

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### DiagonalMatrix

          public DiagonalMatrix(int dimension)
                         throws NotStrictlyPositiveException

      Creates a matrix with the supplied dimension.
      Parameters:
        `dimension` - Number of rows and columns in the new matrix.
      Throws:
        `NotStrictlyPositiveException` - if the dimension is not positive.

    - #### DiagonalMatrix

          public DiagonalMatrix(double[] d)

      Creates a matrix using the input array as the underlying data.
      The input array is copied, not referenced.
      Parameters:
        `d` - Data for the new matrix.

    - #### DiagonalMatrix

          public DiagonalMatrix(double[] d,
                        boolean copyArray)
                         throws NullArgumentException

      Creates a matrix using the input array as the underlying data.
      If an array is created specially in order to be embedded in a this instance and not used directly, the `copyArray` may be set to `false`. This will prevent the copying and improve performance as no new array will be built and no data will be copied.
      Parameters:
        `d` - Data for new matrix.
        `copyArray` - if `true`, the input array will be copied, otherwise it will be referenced.
      Throws:
        `NullArgumentException` - if d is null

  - ### Method Detail

    - #### createMatrix

          public RealMatrix createMatrix(int rowDimension,
                                int columnDimension)
                                  throws NotStrictlyPositiveException,
                                         DimensionMismatchException

      Create a new RealMatrix of the same type as the instance with the supplied row and column dimensions.
      Specified by:
        `createMatrix` in interface `RealMatrix`
      Specified by:
        `createMatrix` in class `AbstractRealMatrix`
      Parameters:
        `rowDimension` - the number of rows in the new matrix
        `columnDimension` - the number of columns in the new matrix
      Returns:
        a new matrix of the same type as the instance
      Throws:
        `DimensionMismatchException` - if the requested dimensions are not equal.
        `NotStrictlyPositiveException` - if row or column dimension is not positive.

    - #### copy

          public RealMatrix copy()

      Returns a (deep) copy of this.
      Specified by:
        `copy` in interface `RealMatrix`
      Specified by:
        `copy` in class `AbstractRealMatrix`
      Returns:
        matrix copy

    - #### add

          public DiagonalMatrix add(DiagonalMatrix m)
                             throws MatrixDimensionMismatchException

      Compute the sum of `this` and `m`.
      Parameters:
        `m` - Matrix to be added.
      Returns:
        `this + m`.
      Throws:
        `MatrixDimensionMismatchException` - if `m` is not the same size as `this`.

    - #### subtract

          public DiagonalMatrix subtract(DiagonalMatrix m)
                                  throws MatrixDimensionMismatchException

      Returns `this` minus `m`.
      Parameters:
        `m` - Matrix to be subtracted.
      Returns:
        `this - m`
      Throws:
        `MatrixDimensionMismatchException` - if `m` is not the same size as `this`.

    - #### multiply

          public DiagonalMatrix multiply(DiagonalMatrix m)
                                  throws DimensionMismatchException

      Returns the result of postmultiplying `this` by `m`.
      Parameters:
        `m` - matrix to postmultiply by
      Returns:
        `this * m`
      Throws:
        `DimensionMismatchException` - if `columnDimension(this) != rowDimension(m)`

    - #### multiply

          public RealMatrix multiply(RealMatrix m)
                              throws DimensionMismatchException

      Returns the result of postmultiplying `this` by `m`.
      Specified by:
        `multiply` in interface `RealMatrix`
      Overrides:
        `multiply` in class `AbstractRealMatrix`
      Parameters:
        `m` - matrix to postmultiply by
      Returns:
        `this * m`
      Throws:
        `DimensionMismatchException` - if `columnDimension(this) != rowDimension(m)`

    - #### getData

          public double[][] getData()

      Returns matrix entries as a two-dimensional array.
      Specified by:
        `getData` in interface `RealMatrix`
      Overrides:
        `getData` in class `AbstractRealMatrix`
      Returns:
        2-dimensional array of entries

    - #### getDataRef

          public double[] getDataRef()

      Gets a reference to the underlying data array.
      Returns:
        1-dimensional array of entries.

    - #### getEntry

          public double getEntry(int row,
                        int column)
                          throws OutOfRangeException

      Get the entry in the specified row and column. Row and column indices start at 0.
      Specified by:
        `getEntry` in interface `RealMatrix`
      Specified by:
        `getEntry` in class `AbstractRealMatrix`
      Parameters:
        `row` - Row index of entry to be fetched.
        `column` - Column index of entry to be fetched.
      Returns:
        the matrix entry at `(row, column)`.
      Throws:
        `OutOfRangeException` - if the row or column index is not valid.

    - #### setEntry

          public void setEntry(int row,
                      int column,
                      double value)
                        throws OutOfRangeException,
                               NumberIsTooLargeException

      Set the entry in the specified row and column. Row and column indices start at 0.
      Specified by:
        `setEntry` in interface `RealMatrix`
      Specified by:
        `setEntry` in class `AbstractRealMatrix`
      Parameters:
        `row` - Row index of entry to be set.
        `column` - Column index of entry to be set.
        `value` - the new value of the entry.
      Throws:
        `NumberIsTooLargeException` - if `row != column` and value is non-zero.
        `OutOfRangeException` - if the row or column index is not valid

    - #### addToEntry

          public void addToEntry(int row,
                        int column,
                        double increment)
                          throws OutOfRangeException,
                                 NumberIsTooLargeException

      Adds (in place) the specified value to the specified entry of `this` matrix. Row and column indices start at 0.
      Specified by:
        `addToEntry` in interface `RealMatrix`
      Overrides:
        `addToEntry` in class `AbstractRealMatrix`
      Parameters:
        `row` - Row index of the entry to be modified.
        `column` - Column index of the entry to be modified.
        `increment` - value to add to the matrix entry.
      Throws:
        `NumberIsTooLargeException` - if `row != column` and increment is non-zero.
        `OutOfRangeException` - if the row or column index is not valid.

    - #### multiplyEntry

          public void multiplyEntry(int row,
                           int column,
                           double factor)
                             throws OutOfRangeException

      Multiplies (in place) the specified entry of `this` matrix by the specified value. Row and column indices start at 0.
      Specified by:
        `multiplyEntry` in interface `RealMatrix`
      Overrides:
        `multiplyEntry` in class `AbstractRealMatrix`
      Parameters:
        `row` - Row index of the entry to be modified.
        `column` - Column index of the entry to be modified.
        `factor` - Multiplication factor for the matrix entry.
      Throws:
        `OutOfRangeException` - if the row or column index is not valid.

    - #### getRowDimension

          public int getRowDimension()

      Returns the number of rows of this matrix.
      Specified by:
        `getRowDimension` in interface `AnyMatrix`
      Specified by:
        `getRowDimension` in class `AbstractRealMatrix`
      Returns:
        the number of rows.

    - #### getColumnDimension

          public int getColumnDimension()

      Returns the number of columns of this matrix.
      Specified by:
        `getColumnDimension` in interface `AnyMatrix`
      Specified by:
        `getColumnDimension` in class `AbstractRealMatrix`
      Returns:
        the number of columns.

    - #### operate

          public double[] operate(double[] v)
                           throws DimensionMismatchException

      Returns the result of multiplying this by the vector `v`.
      Specified by:
        `operate` in interface `RealMatrix`
      Overrides:
        `operate` in class `AbstractRealMatrix`
      Parameters:
        `v` - the vector to operate on
      Returns:
        `this * v`
      Throws:
        `DimensionMismatchException` - if the length of `v` does not match the column dimension of `this`.

    - #### preMultiply

          public double[] preMultiply(double[] v)
                               throws DimensionMismatchException

      Returns the (row) vector result of premultiplying this by the vector `v`.
      Specified by:
        `preMultiply` in interface `RealMatrix`
      Overrides:
        `preMultiply` in class `AbstractRealMatrix`
      Parameters:
        `v` - the row vector to premultiply by
      Returns:
        `v * this`
      Throws:
        `DimensionMismatchException` - if the length of `v` does not match the row dimension of `this`.

    - #### preMultiply

          public RealVector preMultiply(RealVector v)
                                 throws DimensionMismatchException

      Returns the (row) vector result of premultiplying this by the vector `v`.
      Specified by:
        `preMultiply` in interface `RealMatrix`
      Overrides:
        `preMultiply` in class `AbstractRealMatrix`
      Parameters:
        `v` - the row vector to premultiply by
      Returns:
        `v * this`
      Throws:
        `DimensionMismatchException` - if the dimension of `v` does not match the row dimension of `this`.

    - #### inverse

          public DiagonalMatrix inverse()
                                 throws SingularMatrixException

      Computes the inverse of this diagonal matrix.

      Note: this method will use a singularity threshold of 0, use `inverse(double)` if a different threshold is needed.

      Returns:
        the inverse of `m`
      Throws:
        `SingularMatrixException` - if the matrix is singular
      Since:
        3.3

    - #### inverse

          public DiagonalMatrix inverse(double threshold)
                                 throws SingularMatrixException

      Computes the inverse of this diagonal matrix.
      Parameters:
        `threshold` - Singularity threshold.
      Returns:
        the inverse of `m`
      Throws:
        `SingularMatrixException` - if the matrix is singular
      Since:
        3.3

    - #### isSingular

          public boolean isSingular(double threshold)

      Returns whether this diagonal matrix is singular, i.e. any diagonal entry is equal to `0` within the given threshold.
      Parameters:
        `threshold` - Singularity threshold.
      Returns:
        `true` if the matrix is singular, `false` otherwise
      Since:
        3.3

Copyright © 2003–2014 The Apache Software Foundation. All rights reserved.